Email (SMTP)

The SMTP driver sends a real email per event — multipart/alternative with both text/plain and text/html parts, so Gmail/Outlook render the rich layout and terminal MUAs see a usable fallback. It works with any SMTP relay: Gmail (with an app password), Amazon SES, Mailgun, Postmark, SendGrid, or your own Postfix on 127.0.0.1.

Fields

[notifiers.email-ops]
type     = "smtp"
host     = "smtp.example.com"
port     = 587
from     = "RunWisp <[email protected]>"
to       = ["[email protected]"]
username = "apikey"
password = "${RUNWISP_SMTP_PASSWORD}"

The id (as the table key), type, host, from, and at least one to are required. Credentials are optional — leave username and password unset to talk to a local relay (Postfix listening on 127.0.0.1:25, an internal MTA, etc.). Set them together or not at all. Use ${...} substitution to pull the password from an env var or a file — storing the secret.

Key	Required	What it does
`host`	yes	SMTP relay hostname (e.g. `smtp.gmail.com`).
`port`	no	TCP port. Defaults to 25; common values: 587 (STARTTLS), 465 (implicit TLS).
`tls_mode`	no	`"starttls"` (default for 25/587), `"implicit"` (default for 465), `"off"`.
`tls_skip_verify`	no	Skip TLS certificate verification. Do not set this in production.
`username`	no	SMTP AUTH username. Required when sending creds.
`password`	no	SMTP AUTH password — inline, `${VAR}`, or `${file:path}`.
`from`	yes	`From:` header. Accepts `"[email protected]"` or `"Name <[email protected]>"`.
`reply_to`	no	Optional `Reply-To:` header.
`to`	yes	Array of `To:` recipients (at least one).
`cc`	no	Array of `Cc:` recipients.
`bcc`	no	Array of `Bcc:` recipients.
`template_path`	no	Override the embedded HTML message template.

1. Configure the SMTP server

Gmail accepts SMTP on smtp.gmail.com:587 via STARTTLS. Use an app password — Gmail rejects regular account passwords for SMTP.

[notifiers.email-ops]
type     = "smtp"
host     = "smtp.gmail.com"
port     = 587
from     = "Your Name <[email protected]>"
to       = ["[email protected]"]
username = "[email protected]"
password = "${RUNWISP_GMAIL_APP_PASSWORD}"

export RUNWISP_GMAIL_APP_PASSWORD='xxxx xxxx xxxx xxxx'

SendGrid uses a fixed username (apikey) and an API key as the password.

[notifiers.email-ops]
type     = "smtp"
host     = "smtp.sendgrid.net"
port     = 587
from     = "RunWisp <[email protected]>"
to       = ["[email protected]"]
username = "apikey"
password = "${RUNWISP_SENDGRID_API_KEY}"

SES uses dedicated SMTP credentials — generate them in the SES console under SMTP settings, not your IAM password.

[notifiers.email-ops]
type     = "smtp"
host     = "email-smtp.eu-west-1.amazonaws.com"
port     = 587
from     = "RunWisp <[email protected]>"
to       = ["[email protected]"]
username = "AKIA..."
password = "${RUNWISP_SES_SMTP_PASSWORD}"

Same shape — pick the region-appropriate host and use the credentials they issue.

# Mailgun
[notifiers.email-ops]
type     = "smtp"
host     = "smtp.eu.mailgun.org"
port     = 587
from     = "RunWisp <[email protected]>"
to       = ["[email protected]"]
username = "[email protected]"
password = "${RUNWISP_MAILGUN_PASSWORD}"

# Postmark
[notifiers.email-ops]
type     = "smtp"
host     = "smtp.postmarkapp.com"
port     = 587
from     = "RunWisp <[email protected]>"
to       = ["[email protected]"]
username = "<server-token>"
password = "${RUNWISP_POSTMARK_TOKEN}"

A relay you already trust on the same host — no auth, no TLS. The daemon refuses to send credentials over cleartext, so tls_mode = "off" only works alongside an auth-less relay.

[notifiers.email-local]
type = "smtp"
host = "127.0.0.1"
port = 25
tls_mode = "off"
from = "runwisp@myhost"
to   = ["[email protected]"]

2. Store the password

Pick where the password lives and reference it with ${...} substitution.

The simplest option for any deployment — Docker, systemd, bare metal. Set the variable in whatever already manages your environment.

export RUNWISP_SMTP_PASSWORD='your-app-password'
runwisp daemon

[notifiers.email-ops]
type     = "smtp"
host     = "smtp.example.com"
from     = "[email protected]"
to       = ["[email protected]"]
username = "apikey"
password = "${RUNWISP_SMTP_PASSWORD}"

Useful when a secrets manager (Vault agent, sops, Docker secrets at /run/secrets/...) writes the password to a known path for you. Relative paths resolve next to runwisp.toml; ~/ works too.

mkdir -p ~/.config/runwisp
chmod 0700 ~/.config/runwisp
printf '%s\n' 'your-app-password' > ~/.config/runwisp/smtp.password
chmod 0600 ~/.config/runwisp/smtp.password

[notifiers.email-ops]
type     = "smtp"
host     = "smtp.example.com"
from     = "[email protected]"
to       = ["[email protected]"]
username = "apikey"
password = "${file:~/.config/runwisp/smtp.password}"

The notifier accepts password = "..." directly. Avoid it — config files are often committed to git or shared in chat.

[notifiers.email-ops]
type     = "smtp"
host     = "smtp.example.com"
from     = "[email protected]"
to       = ["[email protected]"]
username = "apikey"
password = "your-app-password"

3. Route failures to it

Identical to Slack and Telegram — the routing layer does not care which driver is on the other end:

# On one task:
[tasks.backup-postgres]
notify_on_failure = ["email-ops"]
# …

# Or in a notification rule:
[[route]]
match     = { kinds = ["run.failed", "run.timeout", "run.crashed"] }
notifiers = ["email-ops"]

Inline recipient overrides reuse one credential set across many destinations — notify_on_failure = ["email-ops:[email protected]"] sends through the email-ops relay but to [email protected] instead of the parent notifier’s to list:

[tasks.backup-postgres]
notify_on_failure = ["email-ops:[email protected]"]

You can fan out to multiple channels in the same array — the router sends to all of them, and an outage of one does not stop delivery on the others:

[tasks.critical-job]
notify_on_failure = ["email-ops", "slack-ops", "tg-oncall"]

4. Test it

runwisp run smoke-test       # something that exits non-zero

Emails typically arrive in a few seconds. If yours doesn’t:

Check the bell for a notify.delivery_failed event with the underlying SMTP error.
Common causes: wrong port for the chosen tls_mode (Gmail needs 587 + STARTTLS; SES on 465 needs tls_mode = "implicit"), expired app password, recipient address rejected by the relay (550 No such user).
Spam folder: the first message from a new sender often lands in spam. Whitelist the from address.

What a message looks like

The default template renders one message per event. A failure looks like:

❌ backup-postgres failed

Exited with code 1 after 0.3s. Scheduled run · 14 May, 17:11.
Error: connection refused
dial tcp 127.0.0.1:5432: connect:
connection refused
[View full run]

from runwisp · bright-falcon

The captured-output block appears on run.failed and run.timeout only, capped at three lines / 300 bytes.
The View run link points at <external_url>/tasks/<task>/<id>, taken from [daemon] external_url. When external_url is unset the link is omitted — no broken anchors.
The fingerprint footer identifies the specific daemon that emitted the event.
The plain-text alternative is derived from the HTML body, so terminal MUAs (mutt, mail) see the same content without markup.

template_path overrides the embedded template if you need a different layout. Copy smtp.tmpl.html as your starting point. The helpers statusEmoji, statusVerb, humanTime, humanDuration, runDuration, triggerPhrase, eventSentence, eventTrigger, linkLabel, runURL, taskURL, outputTail, htmlEsc, and fingerprint are available inside it.

What the loader rejects

username set without password — or password set without username. Either both or neither.
tls_mode = "off" combined with credentials — RunWisp refuses to send PLAIN auth over cleartext.
A from, reply_to, to, cc, or bcc value that doesn’t parse as an RFC 5322 address.
A notifier id containing : (reserved for inline target overrides) or equal to "inapp" (reserved).

Email (local MTA)Skip the relay config and use the sendmail binary already on the box.

SlackSame shape, on a different transport.

DiscordColor-coded embeds via a Discord channel webhook.

TelegramSame shape, on a different transport.

WebhookPOST structured JSON to any HTTP endpoint.

Notification rulesOne rule covering many tasks.

Per-task notificationsnotify_on_failure and notify_on_success on one task.