ESP relay accounts (SES, SendGrid, Mailgun, Resend, Postmark, MailerSend)

Coldfeet workers deliver mail via direct MX by default (inbound gateway delivery and outbound without a verified ESP identity). For outbound mail whose header From domain is verified with an ESP, the platform opens an authenticated SMTP session to that ESP — workers are not involved. The same accounts can also terminate inbound MX — see INBOUND-PROVIDER-MX.md.

Inbound gateway delivery to the tenant’s mailbox host always uses the configured smart host (never ESP selection keyed on an external From).

Supported providers

Provider	Outbound	Inbound MX	Notes
Amazon SES	Yes	Yes	IAM for identity API + SMTP credentials. Region required. Receiving in 22 regions.
SendGrid	Yes	Yes	One API key for SMTP (`username=apikey`) and identity API. Disable click/open tracking.
Mailgun	Yes	Yes	Per-domain SMTP credentials created via API and stored on `DomainRelayIdentity`. Tracking forced off.
Resend	Yes	Yes	API key for SMTP (`user=resend`) and domain API. Svix-signed `email.received` webhook; raw MIME via Receiving API.
Postmark	Yes	Yes	Account token + server token (JSON). SMTP uses server token for user+pass. Inbound: URL token + IP allowlist (no HMAC).
MailerSend	Yes	Yes	Per-domain SMTP users. Inbound route HMAC secret. Domains via `POST /v1/domains`.
SparkPost / Bird	No	No	Mid-rebrand API, extra DNS gates.

Adding an account

Admin → Workers → Relay accounts → Add.

Optional: enable inbound MX so domains can point MX at this provider. How that webhook is authenticated differs per provider — only Mailgun needs a signing secret you paste; SES and SendGrid provision verification material automatically (see below).

SES

Create an IAM user with SES identity + account read permissions
Create SMTP credentials in the SES console
Enter region, SMTP username/password, IAM access key id + secret
Click Test connection — if sandbox is detected, request production access
For inbound, run Provision inbound — there is no webhook signing secret to paste

SES has no inbound webhook signing secret. Each SNS message is signed with an Amazon X.509 certificate instead, which Coldfeet verifies. Because a valid signature only proves some AWS account's topic sent the message, ingest also pins the TopicArn, S3 bucket and object prefix to the values Provision inbound created for the account. Notifications from any other topic are rejected, and an account that has not been provisioned cannot receive at all.

SendGrid

Create an API key with Domain Authentication + Mail Send + Inbound Parse
Username is literally apikey; password is the API key
Turn off click tracking and open tracking
For inbound, enable inbound MX — there is no webhook signing secret to paste. Coldfeet auto-provisions a SendGrid security policy (Inbound Parse ECDSA) and enables the signed Event Webhook (bounce ECDSA). The two public keys are distinct and both live in inboundConfig; requests without a valid signature are rejected. Hourly reconcile self-heals missing keys.

Mailgun

Create a private API key (US or EU)
Region us or eu selects API/SMTP hosts
Per-domain SMTP credentials and tracking-disable are handled automatically
Paste the Webhook Signing Key if using inbound MX
Test connection needs a domain with SMTP credentials already minted — pick the domain in the selector beside the button (account-level SMTP is not valid for Mailgun or MailerSend)

Resend

Create an API key with domain + receiving permissions
Username is resend; password is the API key (smtp.resend.com:587)
Enable inbound MX — Coldfeet provisions an email.received webhook and stores the Svix signing secret automatically
Receiving MX is inbound-smtp.<region>.amazonaws.com (see domain wizard)

Postmark

Create an account token and a server token
Paste both on the relay form (account token → apiKey, server token → apiSecret)
SMTP username and password are both the server token
Enable inbound MX — Coldfeet sets InboundHookUrl (with URL token) and InboundDomain on the server. Auth is URL token + Postmark IP allowlist only (weaker than HMAC — see INBOUND-PROVIDER-MX.md)
One custom inbound domain per Postmark server — use separate relay accounts when many domains need provider MX

MailerSend

Create an API token
Per-domain SMTP credentials are created automatically on domain promote
Enable inbound MX; route signing secret is stored when the inbound route is created
Test connection needs a promoted domain (same as Mailgun)

Domain verification UX

When a tenant domain is added (or a relay account is enabled), Coldfeet calls the provider API to create an identity. Returned DKIM/CNAME records appear in the domain’s DNS wizard. Eligibility to send is gated on the provider’s verification status.

Selection

Outbound only, header From domain must have a verified identity
Sticky per sending domain (lowest priority wins when sticky is unset)
Cap spillover: hourly/daily caps move traffic to the next eligible account
Loop guard: never select ESP relay when a recipient domain is hosted here with inboundMode=provider_mx
Identity-level SMTP credentials (Mailgun) override account-level ones
Unverified-identity 5xx → identity failed, same call falls back to worker direct MX
AUTH 535 → account failed, cleared from sticky selection, same-call fallback to direct MX

Asynchronous bounces

ESPs often rewrite the envelope return path. Coldfeet also ingests provider failure webhooks at POST /public/relay-events/:provider so ESP-relayed mail is not silently lost.

Cutover from Postfix

See WORKER-CUTOVER.md.