Skip to content

0029. System mail through Cloudflare Email Service, separate from workspace mail

  • Status: Accepted
  • Date: 2026-11-08

The operator sends its own mail: sign-in codes, account mail, and notifications (plan limits, pauses). Workspace mail (what workspaces send to their customers) goes through Amazon SES (ADR 0024). If system mail shared that SES account and the account were paused, every user would be locked out of sign-in exactly when they need to act. Cloudflare Email Service pricing (checked 2026-11-07 on Cloudflare’s Email Service pricing page): 3,000 emails/month included on Workers Paid, then $0.35 per 1,000. The service is in beta.

  • On the managed service, system mail is sent through Cloudflare Email Service. Workspace mail stays on Amazon SES.
  • System mail goes through a SystemMailer port, separate from the workspace send path; its shape is in the amendment below, which replaces “shaped like EmailProvider”. It does not use the send state machine, workspace budget, or plan limits.
  • Send failures of system mail raise an alert.
  • Self-hosting: a Cloudflare self-host can use Cloudflare Email Service the same way; a container self-host configures its own SMTP or SES for SystemMailer. The first-boot sign-in path (ADR 0025) still works before mail is configured.

Amendment (2026-11-13, when the port was built):

  • The port is narrower than EmailProvider: send(mail) with to, subject, text, and an optional html, and nothing else. No templates, tags, streams, provider events, or webhook verification, because system mail is not metered, tracked, or correlated with messages.
  • The result uses the terms of EmailProvider’s SendResult: accepted with the service’s providerMessageId; rejected when the mail definitely did not reach the recipient, so sending it again cannot duplicate it; unknown when it may have. Every ambiguous case is unknown. rejected and unknown carry a providerReason code, never an address, the mail’s content, or the service’s message text. It differs from SendResult in two ways, because system mail has no send state machine to act on them: rejected has no retryable flag, and there is no unavailable (a paused account or sending limit is rejected). The adapter makes one attempt and never retries; what to do with a failure is the caller’s choice.
  • The sender is configuration, not part of the mail: one system address per installation. On Cloudflare it is the send_email binding SYSTEM_MAIL and the variable SYSTEM_MAIL_FROM, whose domain the operator onboards to Email Service. The repository holds no real address or domain. A missing binding or a missing or malformed SYSTEM_MAIL_FROM fails with an error naming the setting, not its value.
  • There is no no-op or log-only default. System mail carries secrets (approval links, sign-in codes) that a log must not hold (ADR 0032), and a no-op would drop mail a person is waiting for. SystemMailer is not a cloud-only extension point (ADR 0002); self-hosts use it too. An installation without system mail has no SystemMailer, and what needs one fails closed with a configuration error; for send approvals, such installations use SEND_APPROVAL_DELIVERY=response (ADR 0033).
  • Until operator alerts exist, the Cloudflare adapter logs each failure by its outcome and code only.
  • An SES account pause or an SES tenant’s reputation problem cannot block sign-in or notifications, and no extra AWS account is needed.
  • Cost stays within the included 3,000 emails/month at small scale.
  • Risk: Cloudflare Email Service is in beta. Mitigation: because SystemMailer is a port, an adapter for a separate SES account can be added and used as a failover without changing callers.