01The whole path, in one diagram
Five hops from the sending server to the screen. Each one is observable, each one can be the thing that is wrong, and knowing which is which turns “inbound is broken” into a question with an answer.
Everything cheap happens at hop three, inside an open SMTP conversation. Everything expensive happens at hop four, where the CPU budget is 60 seconds.
| Hop | What happens there |
|---|---|
| MX record | Published by Cloudflare itself when you enable Email Routing on the zone. Nothing to copy. |
| Email Routing | A rule matches the recipient and sends the message to a Worker. SPF, DKIM and DMARC are already evaluated here. |
| email() handler | Three things only: does the recipient exist, stream the raw bytes to R2, enqueue. A slow handler defers real mail. |
| ms-inbound queue | Parsing, attachments, threading, spam scoring — where the CPU budget is 60 seconds instead of a few milliseconds of goodwill. |
| R2, D1 and /app/mail | Raw message and attachments in your bucket, headers and threads in your database, the thread list on screen. |
One thing has to be captured at hop three and cannot be recovered later: Authentication-Results. Cloudflare has already run SPF, DKIM and DMARC by the time your handler is called, and it records the verdicts in that header. The connecting IP is gone by hop four, so re-deriving the SPF result there is not merely expensive, it is impossible. The three verdicts are read at the door and carried on the queue message, and they end up as three columns on every inbound row — which is what lets you filter a support inbox by “DMARC failed” rather than guessing from the display name.
02MX records and routing rules
You do not publish MX records by hand. Enabling Email Routing on a Cloudflare zone makes Cloudflare publish its own MX records into the zone it already controls — three of them, at the apex. What you configure is the rule that decides what happens to a message once it has arrived.
In the Cloudflare dashboard: Email → Email Routing, enable it, then add a rule whose action is Send to a Worker and whose script is this instance.
- Lives in the zone, configured in the Cloudflare dashboard
- Decides whether a message for an arbitrary address is handed to your Worker at all
- For most deployments this is the rule you want, because the alternative is maintaining the same address list in two systems and discovering the drift when a message vanishes
- Lives in this instance, on one mailbox
- Decides whether an address with no exact mailbox is accepted once it gets here
- Only one mailbox per domain may hold it, enforced by a partial unique index in the database rather than by the UI — two catch-alls would make delivery depend on row order
| Inside the instance | Routed to the Worker? | What the sender gets |
|---|---|---|
| An exact-address mailbox exists | Yes | Delivered to that mailbox. Exact address always wins. |
| No exact match, one mailbox holds the catch-all flag | Yes | Delivered to the catch-all mailbox. |
| Neither | Yes | 550 5.1.1 No such mailbox — which is why the first message anybody sends to a freshly routed domain bounces if there is no mailbox behind it. |
| Irrelevant — no routing rule | No | The message never reaches the Worker at all. |
Exact address first, then the domain’s catch-all. That order is not arbitrary: a mailbox with its own forwarding webhook, its own agent flag and its own threads must keep receiving its own mail even when a catch-all exists beside it.
03Mailboxes and who can read them
A mailbox is an address plus a small amount of policy. It is the unit that owns threads, the unit a webhook is attached to, and the unit an agent is or is not allowed to touch — which is why support@ and agent@ should be two mailboxes rather than one with a filter.
“Which mail can a model see” is a question about which mailboxes have the agent flag, answered once, in a place you can audit, rather than in a prompt. The flag defaults to off.
POST /v1/inbound/mailboxes
{
"address": "[email protected]",
"name": "Support",
"is_catch_all": true,
"agent_enabled": false // an MCP agent cannot see this mailbox
}The agent flag is a scope boundary, not a preference. The MCP server reads mail through the same mailboxes you do. An agent inbox on its own address is inspectable, revocable and separable in the logs; an agent given read access to your whole support queue is none of those things.
| On every inbound row | What it holds |
|---|---|
| from_address, to_addresses | The envelope as it arrived. |
| subject, snippet | What the thread list shows without opening anything. |
| parse_status | Whether the MIME parse on the queue consumer succeeded. |
| matched_by | Which rule matched — the exact address, or the catch-all. |
| spf, dkim, dmarc | The three edge verdicts, captured at hop three. |
| spam_score | Scored on the queue consumer, where there is CPU budget for it. |
| raw_key, body_key | Two R2 keys: the raw RFC 5322 bytes exactly as they arrived, and the extracted body. Both in your own bucket. |
04How replies get threaded
When MailySend sends a message that expects a reply, the reply-to address carries a signed token: reply+<token>@inbound.yourdomain.com. When the reply comes back, that token names the thread it belongs to, with no heuristics involved.
The token is the workspace id and the thread id, base64url encoded, with a truncated HMAC over that payload appended — so verification is a hash and a timing-safe comparison, with no database lookup.
To: [email protected] From: [email protected] In-Reply-To: <[email protected]> Reply-To: reply+eyJ3cyI…[email protected] ← the signal
This is a higher-confidence signal than References, and the reason is behavioural rather than theoretical. Mail clients mangle References: they truncate it, drop it on a forward, rebuild it wrongly after an edit, and rewrite subjects with localised Re: prefixes that a naive normaliser will not match. What clients reliably preserve is the address they were told to reply to — that is the one field the entire user interface is built around. There is also no way to point a reply at somebody else’s thread by editing the address, because a forged token fails the signature check.
05The one thing that cannot be shown
There is one piece of this setup the dashboard cannot show you, and rather than inventing a plausible indicator it links you to the place where the real value lives. Cloudflare’s Email Routing catch-all rule is not readable over its API. Not rate-limited, not awkward — not exposed.
So the receiving panel says what it measured, says what it did not, and puts a button straight to the Email Routing page for the one thing you have to confirm with your own eyes.
| Fact | Can the dashboard know? |
|---|---|
| MX points at Cloudflare | Yes — a DNS lookup |
| A mailbox exists on this domain | Yes — its own database |
| A mailbox holds the catch-all flag | Yes — its own database |
| Email Routing’s catch-all rule sends to this Worker | No — not exposed by the API |
The tempting design is a green tick that means “MX verified” and lets the reader infer the rest. That is the version this product refuses to ship. A verified MX is not a working setup, and an indicator that reads like one converts a five-minute configuration check into an afternoon of debugging a system that was telling you it was fine.
In the Cloudflare dashboard for this zone. This is the one piece of state the product cannot read for you.
Its action must be Send to a Worker, and the script must be this instance.
Then watch it appear in the mail screen. About thirty seconds, and it is the only test that covers every hop.
What just happened
Mail addressed to your domain now lands in a mailbox you can read, with the raw bytes and any attachments in your own R2 bucket and the edge’s SPF, DKIM and DMARC verdicts recorded against each message. The thing most likely to bite you is that receiving needs two things to be true in two different places — a Cloudflare routing rule pointing at this Worker, and an address that exists inside the instance. Get one without the other and the first test message bounces with a 550, which looks like a broken deployment and is not one.