Skip to content

App and Transactional Email: Cloudflare and Brevo

App mail is everything a program sends rather than a person: password resets, invites, meeting reminders, order notices, and alerts from servers such as GitLab or Proxmox. It has different needs from people’s mail. It must arrive quickly, nobody replies to it, and one bug can send thousands of messages. This page covers the services the community uses for it and the rules that keep it from being abused.

For the bigger picture (what to self-host and what to rent) see Running Your Own Email.

Send app mail from a subdomain such as mail.example.org, not from the domain people use.

  • Reputation stays separate. A burst of bounced reminders can’t hurt delivery of people’s mail, and the reverse.
  • DMARC can be strict. Nobody sends from the subdomain by hand, so it can carry p=reject while the main domain is still at quarantine.
  • SPF stays simple. The provider’s records go on the subdomain, so the apex SPF record doesn’t grow another include:.

Use an address that says what sent it (gitlab@, events@, merch@), not a person’s name.

Cloudflare Email Service has two parts. Neither one hosts a mailbox.

Email Routing receives mail for a domain and either forwards it to a verified destination address (any mailbox you’ve confirmed you own) or hands it to a Worker’s email() handler. It’s available on the Workers Free and Paid plans, with up to 200 routing rules per domain.

It works by taking the domain’s MX records, so it can’t share a name with your own mail server. Use it for domains that only need forwarding (info@, contact@), or for a subdomain whose mail a Worker processes.

Traps to know about:

  • Rules outlive “disabled”. Turning Email Routing off doesn’t delete the zone’s rules, and they keep catching mail from senders that cached the old MX. After moving a domain’s MX away, list the rules and delete the ones you don’t want (the mailcow page has the API calls).
  • Review destination addresses. A verified destination stays verified for years. If the domain behind that address lapses and someone else registers it, any rule or Worker forward() to it delivers to them. Delete destination addresses you no longer control.
  • “Misconfigured” means the MX is elsewhere. If Routing is enabled for a zone whose MX points at another provider, its rules never fire. Turn Routing off there, or move the MX.

Email Sending delivers mail from a domain you’ve onboarded. There are three ways to send:

  1. The Workers binding. Add [[send_email]] with a name to wrangler.toml and call env.<NAME>.send(). A successful send returns a messageId; store it.
  2. The REST API, for anything that can make an HTTPS request.
  3. Authenticated SMTP, for software that only speaks SMTP (GitLab, monitoring tools).

Sending to arbitrary recipients needs the Workers Paid plan; sending to your own verified destination addresses is free. The product is in beta, so read the current docs before you rely on a detail.

Limits (from Cloudflare’s limits page): 50 recipients per message across to, cc and bcc; 5 MiB per message including attachments; a daily quota that starts low for new accounts and grows with good sending behaviour. The quota is shared by everything on the account, so one runaway sender can stop the others.

DNS. Onboarding a domain or subdomain adds records under cf-bounce.<domain>: a bounce MX, an SPF record (include:_spf.mx.cloudflare.net) and a DKIM key at cf-bounce._domainkey.<domain>. Cloudflare recommends p=reject DMARC on the sending domain. It doesn’t change the apex SPF record.

SMTP settings:

SettingValue
Hostsmtp.mx.cloudflare.net
Port465, implicit TLS only. There’s no STARTTLS on 587.
Usernamethe literal string api_token
Passworda Cloudflare API token with the Email Sending: Edit permission
Per-session limits50 RCPT TO; 5 MiB message size

Give each sender its own token with only that permission, so you can revoke one without touching the others. A leaked token can send as your domain from anywhere and use up the shared daily quota. Restrict it by client IP where you can, and test from another address that the restriction is enforced.

Handle the error codes. The Workers API throws typed errors. Retry only the transient ones, with backoff:

Retry laterDon’t retry (fix the cause)
E_DELIVERY_FAILED, E_RATE_LIMIT_EXCEEDED, E_INTERNAL_SERVER_ERRORE_SENDER_NOT_VERIFIED, E_SENDER_DOMAIN_NOT_AVAILABLE, E_RECIPIENT_NOT_ALLOWED, E_RECIPIENT_SUPPRESSED
E_DAILY_LIMIT_EXCEEDED (after the quota resets, not in a loop)E_VALIDATION_ERROR, E_FIELD_MISSING, E_TOO_MANY_RECIPIENTS, E_CONTENT_TOO_LARGE, the E_HEADER* errors

Older guides list other names (E_INVALID_TO, E_RECIPIENT_BOUNCED). Check the current list in the Workers API docs.

If you build raw MIME with the mimetext library instead of the structured API, wrap address headers in its Mailbox type (new Mailbox(addr)); a bare string for Reply-To throws.

Our GitLab sends notifications through the Email Sending SMTP endpoint as gitlab@mail.irregulars.io. Before that, it had no SMTP settings at all, so it fell back to sendmail, which the GitLab Omnibus image doesn’t ship. Every notification from at least April to October 2026 failed: 6,033 messages, mostly pipeline failures plus merge request, issue and access-granted mail. Nothing noticed, because:

  • in-app to-dos kept working;
  • GitLab records a notification before delivering it, so the records proved nothing;
  • the failed jobs sat in Sidekiq’s dead set, which nobody watched.

What fixed it, and what keeps it fixed:

  1. SMTP settings pointing at the endpoint above, with a token used by GitLab alone.
  2. A daily health check that fails (and alerts) when GitLab’s delivery method isn’t SMTP, the SMTP password is empty, email is disabled, a mail job died in the last 25 hours, or a mail job has been retrying for over an hour.
  3. Don’t replay old mail. After a fix, delete the stale dead mail jobs instead of retrying them, or members get months of old notifications at once.

The same pattern applies to any server that sends mail: configure a real relay, then check the delivery path, not just that the app thinks it sent something.

Brevo (formerly Sendinblue) offers an SMTP relay and a transactional API, plus marketing campaigns. We used its relay as the smarthost for our self-hosted mail server, because our mail IPs have no reverse DNS (see mailcow), until 2026-10-20, when we moved to Amazon SES because of the tracking described below.

  • Relay vs API. The relay is smtp-relay.brevo.com on port 587 (or 2525) with STARTTLS, or 465 with TLS. The v3 REST API takes an api-key header.
  • An SMTP key is not an API key. Brevo issues separate SMTP keys and API keys, and its docs say to use an SMTP key, not an API key, for the relay. Code that sends an SMTP key to the API (or the reverse) fails to authenticate.
  • Authenticate the domain. Brevo issues a verification TXT record (brevo-code:…) and DKIM records: on some accounts two CNAMEs (brevo1._domainkey, brevo2._domainkey), on others a TXT key. Publish exactly what your account shows, and keep your mail server’s own DKIM selector alongside them.
  • SPF. On Brevo’s shared IPs the envelope sender (Return-Path) is normally a Brevo domain, so SPF is checked against Brevo, and DMARC passes on the aligned DKIM signature. Check a received message’s Return-Path to confirm. If you list Brevo in your SPF record anyway, the include that carries its sending ranges is include:spf.brevo.com. Two lookalikes are wrong: _spf.brevo.com publishes v=spf1 -all (it authorises nothing), and sendinblue.com is Brevo’s corporate record, which also authorises Google, Zendesk and Intercom.
  • Tracking is on by default, even on the SMTP relay. We checked on 2026-10-20: an HTML message relayed through Brevo arrived with every link rewritten to a Brevo tracking domain and two tracking images added, plus Brevo’s own List-Unsubscribe headers. The plain-text part was untouched. Brevo’s settings can anonymize tracking; turning it off entirely is offered on request on Enterprise plans. For newsletters that’s normal. For a smarthost it means every HTML message your people send to outside addresses, and every HTML email an alias service forwards, is tracked by a third party.
  • Logs are kept indefinitely by default. Set transactional log retention to the minimum (one month) and keep message previews off.
  • One account, shared fate. Sub-accounts (“sub-organizations”) are an Enterprise feature, so on other plans every tenant and every forwarded message counts against one account and its daily cap (300 a day on the free plan). Brevo’s terms let it suspend or end the free service at any time, and spam forwarded by an alias service is exactly what gets accounts suspended, taking all your outbound mail with it.
  • No bounces through the relay. Brevo refuses mail with an empty envelope sender (the MAIL FROM:<> used by bounce notices) with 451 4.0.0 Invalid from. If your mail server routes its own bounce notices through Brevo, they sit in the queue retrying until they expire. Better still, reject mail for unknown addresses during the SMTP conversation, so your server never has to send a bounce (sending bounces to forged senders is called backscatter).
  • Marketing mail needs consent. Newsletters need opt-in, an unsubscribe link and one-click unsubscribe. A transactional relationship isn’t consent to marketing.

Since 2026-10-20 our mail server and alias service relay through Amazon SES’s SMTP interface. What we learned setting it up:

  • It doesn’t touch the message. We sent the same HTML test through Brevo and through SES to a mailbox we control. Through SES the links were intact, there were no tracking images, and the only additions were SES’s Feedback-ID and X-SES-Outgoing headers and a second DKIM signature (d=amazonses.com). SES only tracks opens and clicks if you set that up in a configuration set.
  • It replaces the Message-ID with one of its own (…@<region>.amazonses.com). Replies reference SES’s ID, so a sender’s mail client may not thread a reply with the copy in its Sent folder. Brevo kept the original.
  • Pick the region on purpose. Sending limits, the sandbox and account health are tracked per region. If the same AWS account already sends something important (a shop’s order mail, say) from one region, put community and alias mail in another, so a spam-forwarding incident can’t get the other project’s sending paused.
  • New regions start in the sandbox: you can only send to verified addresses until you request production access. Describe the traffic honestly, including alias forwarding. Ours was granted the same day.
  • Verify every sending domain with Easy DKIM (three CNAMEs, 2048-bit, DNS-only in Cloudflare). SES rejects mail whose sender domain isn’t verified, so an alias service needs its own domain verified too, and every new tenant domain has to be added before it sends.
  • SPF needs no change. SES’s default envelope sender is its own domain, so receivers check SES’s SPF and DMARC passes on your aligned DKIM. A custom MAIL FROM subdomain adds aligned SPF if you want it.
  • Use a send-only credential. Create an IAM user whose only permission is ses:SendRawEmail, limited to your region with an aws:RequestedRegion condition. The SMTP username is its access key ID; the SMTP password is derived from the secret key, so derive it in a script and keep it out of your terminal history.
  • The console’s “Create SMTP credentials” wizard now goes through Mail Manager. Its “Advanced settings” step creates a Mail Manager traffic policy, rule set, IAM role and ingress endpoint, and the credentials it gives you belong to that endpoint: they’re rejected by the classic email-smtp.<region>.amazonaws.com endpoint (535 Authentication Credentials Invalid). Per the pricing page the authenticated endpoint itself is free, but Mail Manager adds processing charges per message, and open or mTLS endpoints cost $50 a month each, even when closed. For a smarthost, skip that step (or create the IAM user directly), and don’t add the user to the console’s default sending group, which allows every region.
  • Bounce notices still don’t go through it. Like other relays, SES won’t relay mail with an empty envelope sender, so leave your server’s own bounce notices on direct delivery.
OptionCost modelGood forNotes
Cloudflare Email SendingWorkers Paid planMail from Workers; SMTP for serversBeta; transactional mail; daily quota shared across the account
BrevoFree tier with a daily cap; paid plansTransactional and marketing mailSMTP keys and API keys are separate; adds link and open tracking to relayed HTML by default
Amazon SESPay per message ($0.10 per 1,000 at list price)A smarthost for a self-hosted server; app mailSandbox until production access; per-region setup; no tracking unless configured; replaces the Message-ID
PostmarkPaidTransactional mail where delivery speed mattersSeparate streams for transactional and broadcast mail
Your own server through a relayYour hardware plus the relayMail from your own domainsSee mailcow

Whatever you pick, publish its DKIM records, give it its own subdomain, and keep DMARC reports flowing (Email DNS Authentication).

Anything that sends mail on a user’s behalf is a target. Spammers look for forms that send DKIM-signed mail from a real domain to an address they choose. Each rule below closes a common hole.

  • Never let an anonymous caller choose both the recipient and the content. That’s an open relay signed with your domain. Any endpoint that sends mail must require a real login (or a server-to-server secret), and any text a user typed must be clearly framed or left out.
  • Throwaway accounts can’t send invites. If your app allows anonymous or self-registered accounts, block them from every action that emails someone else (invites, sharing, adding members by email).
  • Verification emails carry no user text. Don’t put the name someone typed into “Hi {name}”: cap field lengths, and send at most one verification mail per address per day.
  • Rate-limit per recipient and globally, not only per IP. Per-IP limits are easy to spread across many addresses; bucket IPv6 by /64. If the limiter’s storage fails, fail closed for mail-sending routes.
  • Write the record before the send. Insert an outbox row with a unique key per (message type, recipient, object), send, then mark it sent or failed. Treat a timeout as an unknown outcome to review, not a failure to retry, or people get duplicates.
  • Don’t spend single-use links on GET. Corporate link scanners open every link in an email first. Show a confirmation page on GET and redeem the token on POST.
  • Keep addresses and bodies out of logs. Log a message ID and a masked address (j***@example.org).
  • Don’t copy every message to a personal mailbox. Audit copies double your quota use and put working links (claim links, password resets) into a mailbox that wasn’t the recipient’s. Keep an audit row in the database instead.
  • Escape everything you put in an HTML body, and only build links from your own base URL plus IDs and tokens.

Recent changes

  1. docs: record the move from Brevo to Amazon SES for outbound mail gitayam
  2. docs(wiki): add smarthost-vs-direct guidance and two mail server lessons gitayam
  3. docs(wiki): reorganize the email guides for self-hosters gitayam