0029. System mail through Cloudflare Email Service, separate from workspace mail
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”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.
Decision
Section titled “Decision”- On the managed service, system mail is sent through Cloudflare Email Service. Workspace mail stays on Amazon SES.
- System mail goes through a
SystemMailerport, separate from the workspace send path; its shape is in the amendment below, which replaces “shaped likeEmailProvider”. 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)withto,subject,text, and an optionalhtml, 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’sSendResult:acceptedwith the service’sproviderMessageId;rejectedwhen the mail definitely did not reach the recipient, so sending it again cannot duplicate it;unknownwhen it may have. Every ambiguous case isunknown.rejectedandunknowncarry aproviderReasoncode, never an address, the mail’s content, or the service’s message text. It differs fromSendResultin two ways, because system mail has no send state machine to act on them:rejectedhas noretryableflag, and there is nounavailable(a paused account or sending limit isrejected). 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_emailbindingSYSTEM_MAILand the variableSYSTEM_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 malformedSYSTEM_MAIL_FROMfails 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.
SystemMaileris not a cloud-only extension point (ADR 0002); self-hosts use it too. An installation without system mail has noSystemMailer, and what needs one fails closed with a configuration error; for send approvals, such installations useSEND_APPROVAL_DELIVERY=response(ADR 0033). - Until operator alerts exist, the Cloudflare adapter logs each failure by its outcome and code only.
Consequences
Section titled “Consequences”- 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
SystemMaileris a port, an adapter for a separate SES account can be added and used as a failover without changing callers.