Receive mail

You need: a domain whose MX you are willing to point at Cloudflare.

One entry, fanned out

The MX constraint is the decision to take before any of this, provisioning support stands it up, running a support inbox is the customer-mail half, and bounces and suppression is the machine half.

Mail arrives at your app Worker’s single email() entry, which fans it to every capability that handles inbound mail.

Today that is two:

CapabilityClaims
emailBounce and complaint mail
supportWhatever is addressed to a configured support address

Recipient matching is on the envelope

On the SMTP envelope recipient. Never on a To: header.

Anyone can put your support address in a header on a message routed somewhere else.

The envelope is authority; headers are not — and the same rule applied to the sender is what provenance is about.

Two routing rules, deliberately named apart

RuleDelivers
<project>-global-email-bounceBounce and complaint mail
<project>-<env>-support-inboundYour support address, one rule per environment. The override flags make one <project>-global-support-inbound instead

The bounce rule is found by its name. Sharing one would make whichever capability provisioned second silently believe its rule already existed. Support’s rule is found by the address it matches: one already sending that address to the Worker is left alone, whatever it is called.

And the project segment stops two Pithy projects on one zone doing that to each other — with the loser’s mail delivered to the winner’s Worker.

Neither turns Email Routing on

pithy email provision   --routing-zone <zone-id> …
pithy support provision

Turning Email Routing on for the wrong domain would move your real mail, and that is not a mistake a provisioning command gets to make on your behalf. So that switch is always yours, in the Cloudflare dashboard. pithy email provision takes the bounce rule’s zone, address and Worker as explicit flags. pithy support provision derives its rule per environment from support’s inboundAddresses, on the zone that holds each address’s domain, and routes only a domain whose Email Routing you have already enabled.

Leave email’s flags off, or Email Routing off for support’s domain, and everything else still provisions. Support names the domain it refused and where to turn it on.

Teardown removes the rule first

So mail stops arriving before the Workers that would have handled it go away.

pithy support deprovision --env <environment> finds that environment’s rule from the addresses it claims, and removes only a rule sending one of them to its own Worker. A rule sending the address anywhere else is left alone.

What happens to a message support claims

The guard bounds it. It is parsed — multipart and attachments included. The HTML is sanitized through the runtime’s own parser. The raw MIME goes to R2 unchanged. The row lands in D1.

Only then is classification dispatched, as a Workflow — because an inbound handler has a tight CPU budget and a model call does not fit in it.

A model that is slow or briefly down must never take the persistence of somebody’s support request with it.

Threading is on headers

In-Reply-To and References. Never the subject.

Subject matching puts two unrelated people who both wrote “Refund” in one thread, and splits a real conversation the moment a client localizes Re: to Aw:.

Until you configure an address, the inbox is inert

It ignores every message and says so once in the log — rather than quietly storing mail from an address nobody chose.

ESC