Stanchion docs

Stanchion (formerly cMail): the docs and code keep the old name until the code is renamed.


Standby test address and daily probe

Status: built, off by default, not yet tested against real DNS or a real Cloudflare account. The code paths are covered by tests with a mocked Email Sending binding and a simulated Email Routing delivery (see How to test).

Unproven for the main use case. Cloudflare Email Routing needs exclusive control of the root domain's MX records: onboarding fails with error 2008 ("Non-Cloudflare MX records exist") while another provider's MX is there (domains, troubleshooting). Subdomains are added from the apex domain's Email Routing settings (subdomains). So the case this feature is for, with the apex MX at Exchange Online and only standby.<domain> at Cloudflare, may not be possible at all. Try it on a real test account before anyone turns this on. If it cannot be done, the standby address does not work on that domain, whatever the code does.

When cmail is kept as a standby for another mail system (for example Exchange Online), the main domain's MX records point at the other system, so nothing proves day to day that cmail would receive mail if you switched. This feature gives every mailbox a second address on a subdomain whose MX already points at Cloudflare, and sends a test message through it once a day.

Architecture

 cron */10 (email Worker)            Cloudflare                    email Worker email()
 ──────────────────────────          ─────────────────────         ──────────────────────────────
 switch on? config ok? lease          Email Sending                 exact address? no
 time out overdue probes      ──▶    (from probe@example.com) ──▶  standby address? yes ─▶ probe mailbox
 prune old probes                     delivery to                   probe token known and live?
 daily probe due? ─ send ─────────▶   standby.example.com           store via the normal path
   insert run (waiting)               (path inside Cloudflare       record pass + round trip
                                      not verified), Email Routing
                                      literal rule ─▶ this Worker
Part Where
Switch, config, alias mapping, status light packages/shared/src/standby.ts
Alias lookup, probe send, receipt, timeout, pruning apps/email-worker/src/standby/standby.ts
Inbound wiring (alias, probe gate, receipt) apps/email-worker/src/index.ts, email()
Private endpoints GET /internal/standby/config, POST /internal/standby/run on cmail-email-worker.internal (service binding only)
Admin page apps/web/src/routes/admin/standby/, apps/web/src/lib/server/standby-admin.ts
Tables standby_probe_runs, standby_probe_state (migration 0023)

The standby address

The inbound handler first looks up the exact recipient as before. Only if that finds no active mailbox does it try the standby mapping:

  1. The recipient's domain must equal <STANDBY_SUBDOMAIN_LABEL>.<MAIL_DOMAIN> exactly. Deeper subdomains (a@x.standby.example.com) and look-alikes are not mapped.
  2. The local part is kept and the domain replaced by MAIL_DOMAIN.
  3. One query requires, together: the manager switch is on, and a mailbox exists at that primary address with status active. That is exactly the primary address's own rule, so the standby address always answers the same way as the primary one and cannot be used to learn whether an account is paused or offboarded.

Anything that does not match gets the same neutral permanent refusal as an unknown address on the primary domain, and nothing is written to D1 for it.

What this means for safety:

Plus addressing (name+tag@...) is not mapped, in the same way the primary domain looks up exact addresses only.

The probe

Status light

Light When
Off The switch is off
Green The newest finished test passed within the last 26 hours, with no warning that matters
Amber It passed with a warning (filed to Spam, DMARC not pass, or slower than 5 minutes); the last pass is 26 to 50 hours old; or no test has finished yet
Red The newest finished test failed (reason shown); a running test is overdue; or no pass for 50 hours

"SPF, DKIM and DMARC were not recorded" (no INBOUND_AUTHSERV_ID) is shown but does not make the light amber.

Failure reasons: timeout, late, send_rejected (with the Email Sending error code, for example E_SENDER_NOT_VERIFIED), send_failed (an ambiguous or network failure), no_send_binding, probe_address_in_use, probe_mailbox_disabled, probe_mailbox_missing.

What a green light means, and what it does NOT mean

Green means: within the last day, a message sent by Cloudflare Email Sending to the standby address was delivered by Cloudflare Email Routing to this email Worker, passed the same inbound checks as any mail, and was stored in D1 and R2 within the time limit.

Green does not mean:

Amber or red is a reason to look, not proof of an outage: one failed probe can be a short Cloudflare delay. Run test now to check again.

How to set up the standby test

Onboarding a Microsoft 365 organisation end to end? See the onboarding guide, steps 9 and 12.

Do these in order. DNS and Email Routing changes are live changes; follow your own change process.

  1. Migration. Apply 0023 (pnpm db:migrate). Additive: two new tables.
  2. Email Worker settings (apps/email-worker/wrangler.toml):
    • MAIL_DOMAIN: the same value as the web app's.
    • STANDBY_SUBDOMAIN_LABEL (default standby), STANDBY_PROBE_LOCAL_PART (default cmail-standby-probe), STANDBY_PROBE_TIMEOUT_MINUTES (default 10, 2 to 60).
    • The [[send_email]] name = "EMAIL" binding (already in the example).
    • Add "*/10 * * * *" to [triggers] crons. Without it no daily probe runs and the light goes amber, then red.
  3. Email Sending must already be set up for MAIL_DOMAIN (cmail's normal outbound mail). The probe is sent from an address on it. Once a sending domain is onboarded it can send to any recipient (limits).
  4. Email Routing on the subdomain. In the dashboard, Email Service > Email Routing > the apex domain > Settings > Subdomains, add standby.<your domain>. Cloudflare adds the MX and other records on the subdomain (subdomains).
  5. Routing rules on the subdomain. Catch-all rules are only available on the apex domain; a subdomain needs a literal rule per address, each with the "Send to a Worker" action pointing at the cmail email Worker (routing rules). At minimum add cmail-standby-probe@standby.<your domain>, then one rule per person or shared mailbox that should have a standby address. Email Routing allows 200 rules per domain (limits), so a larger organisation can only cover its key addresses this way.
  6. Turn it on in Admin > Standby test, then press Run test now.

To turn it off, use the switch: mail to the standby domain is refused at once and no more tests run. The routing rules and DNS can stay.

Troubleshoot the standby test

Shown Likely cause What to do
Not configured A setting is missing or invalid (names listed) Fix the Worker setting and redeploy the Worker
no_send_binding The Worker has no EMAIL binding (for example the preview Worker) Add [[send_email]] name = "EMAIL"
send_rejected E_SENDER_NOT_VERIFIED / E_SENDER_DOMAIN_NOT_AVAILABLE MAIL_DOMAIN is not onboarded to Email Sending Onboard it, or check the probe local part is on that domain
send_rejected E_RATE_LIMIT_EXCEEDED / E_DAILY_LIMIT_EXCEEDED The account's sending limit was hit Check outbound volume; the next daily probe retries
send_failed A network error or an ambiguous answer from Email Sending Run test now; if it repeats, check the Cloudflare status page
timeout No arrival in time: missing literal routing rule for the probe address, subdomain MX not in place, routing rule pointing at another Worker, the Worker failing on delivery, or a slow delivery Check the rule and MX in the dashboard, Email Routing activity and the Worker logs; Run test now
late Arrived after the timeout One-off: ignore. Often: raise STANDBY_PROBE_TIMEOUT_MINUTES and investigate delays
probe_address_in_use Another mailbox already has the probe address, including an old probe mailbox after you changed the local part back Set STANDBY_PROBE_LOCAL_PART to an unused local part, or delete the old mailbox in Admin > Mailboxes
probe_mailbox_disabled A manager disabled the probe mailbox Re-enable it in Admin > Mailboxes
Amber: filed to Spam The organisation sender list blocks MAIL_DOMAIN, or SPAM_QUARANTINE_SCORE caught it Review the sender rules and threshold
Amber: DMARC did not pass Email Sending DKIM or the domain's DMARC record is wrong Check the Email Sending DNS records
Amber/red: stale The */10 cron is missing or the Worker is failing Check [triggers] and the Worker logs

Cloudflare's Email Routing summary may show messages a Worker sent with the send_email binding as "dropped" even when they were delivered (limits). Use the Admin page, not that summary, for the probe.

How to test

Automated (no Cloudflare account needed):

By hand, on a test domain first:

  1. Complete Setup on a test domain and turn the switch on.
  2. Run test now: within a minute the light is green with a round trip.
  3. Send from an outside mailbox to <someone>@standby.<test domain> (with a literal rule for it): the message appears in that person's mailbox, and Mail trace shows the standby address.
  4. Send to an address on the subdomain with no cmail mailbox (but a rule): the sender gets a refusal.
  5. Disable that person's mailbox in Admin > Mailboxes and send again to both addresses: both refused the same way.
  6. Remove the probe address's routing rule and Run test now: red timeout after the timeout (on the next cron run). Put the rule back.
  7. Turn the switch off and send to the standby address: refused.

Not verified yet (needs a real account):