Email

WatchDeck’s email channel is bring-your-own SMTP — you supply a connection URL and one or more recipient addresses, and the dispatcher uses nodemailer  to deliver the message. There’s no shared sending domain or hosted email service involved, which means deliverability is yours to own (no shared-domain reputation issues, no per-tenant rate limits) but also means you need an SMTP relay to point at.

Use any SMTP provider — your own server, Postmark, SES, Mailgun, SendGrid SMTP, Resend SMTP, etc.

Required fields

The endpoint URL is encrypted at rest (AES-256-GCM) and never sent back to the browser after creation. If you need to rotate it, paste the full new URL — leaving the field blank on edit keeps the existing value.

URL format examples

smtps://USER:PASS@smtp.postmarkapp.com:465
smtps://AKIAEXAMPLE:secret@email-smtp.us-east-1.amazonaws.com:465
smtp://user@your-relay.example.com:587

Use smtps:// for implicit TLS (port 465). Use smtp:// for STARTTLS or plain (587 / 25). Most modern providers accept both — pick whichever your provider documents.

What gets sent

The from-address is derived from the SMTP URL:

• If the URL’s username is itself an email (e.g. notifications@yourdomain.com), that’s the from-address.
• Otherwise, WatchDeck synthesises notifications@<smtp-host>.

The display name is your channel’s Name, lightly sanitised. So a channel called “Ops on-call” using smtps://alerts@example.com:... sends as:

"Ops on-call" <alerts@example.com>

The subject is <title> — <channel name>, e.g. Endpoint down — Ops on-call.

The body is sent in both HTML and plaintext. The HTML version uses an inline-styled table with a severity-coloured banner:

The plaintext version is the same content without styling.

Connection handling

WatchDeck caches one nodemailer transporter per channel id, so consecutive sends reuse the same TLS session. Connection, greeting, and socket timeouts are each 15 seconds. On any send failure the transporter is dropped and re-created on the next attempt.

Test send

Click Test on the channel card to fire a synthetic channel_test message at your recipients. The result is shown inline on the card and recorded in the Delivery log with kind='channel_test'.

A successful test sets is_connected=true and updates last_success_at; a failed test does the opposite. Live (incident) dispatches don’t update these columns — see connectivity status.

Failure handling

There’s no retry path on the cloud dispatcher today, so a failed delivery stays failed. Re-running Test is the fastest way to confirm a fix.

Troubleshooting

• “Greeting timeout” — your provider doesn’t accept connections on the port in your URL, or a firewall is between WatchDeck and your provider. Most providers prefer 465 (smtps) or 587 (smtp+STARTTLS).
• “Invalid login” — credentials in the URL are wrong, or the provider expects an API key (not a password). Postmark and Mailgun both want API tokens, not user passwords.
• Email lands in spam — your SMTP relay’s from-domain isn’t authenticated (SPF / DKIM / DMARC). Fix that on your provider — WatchDeck has no control over the from-domain.
• Different recipients see different things — they shouldn’t. The same HTML+text body is delivered to every recipient; differences are usually rendering quirks (Outlook strips inline CSS aggressively).

Quotas and limits

• Counts toward your per-plan channel cap — see Notifications → Quotas.
• No per-channel send-rate limit is enforced today. If your SMTP provider rate-limits you, errors will surface as failure_reason on the log row.

What’s next