Worker settings, storage format, and setup script options
This page lists the Worker’s settings and limits, how it stores each email in R2, and the options of the setup script and npm scripts. For task-based instructions, see Control which emails your inbox accepts and keeps.
Worker settings
The Worker reads its settings from vars in worker/wrangler.jsonc. All of them are optional, and changes take effect after npm run deploy.
| Setting | Default | Description |
|---|---|---|
ALLOWED_SENDERS |
Empty, so every sender is accepted | Comma-separated addresses and @domain entries. Mail from any other envelope sender is rejected. |
REQUIRE_DMARC |
false |
When true, mail whose DMARC result isn’t pass is rejected |
FORWARD_TO |
Empty | An address that gets a copy of each stored email. Must be a verified Email Routing destination. |
PREFIX |
mail |
The top folder for stored emails. Trailing slashes are removed. |
ALLOWED_SENDERS matching works like this:
- Entries are trimmed and compared without regard to case
- A full address matches only that exact envelope sender
- An
@domainentry matches envelope senders ending in@domain, so subdomains don’t match - An empty list accepts every sender
Other Worker config
The rest of worker/wrangler.jsonc sets how the Worker is deployed:
| Key | Value | Why |
|---|---|---|
name |
r2-mailbox |
The Worker name that routing rules point to |
main |
src/index.ts |
The Worker’s code |
account_id |
Commented out | Set it if your login has more than one account |
workers_dev |
false |
No *.workers.dev address |
preview_urls |
false |
No preview URLs |
r2_buckets |
Binding MAILBOX to r2-mailbox |
The bucket the Worker writes to |
observability |
{ "enabled": true } |
Saves Worker logs to the dashboard |
What the Worker does with each email
The Worker runs the same checks in the same order for every email:
- If the email is larger than 20 MiB (20,971,520 bytes), reject it with
Message too large. - If
ALLOWED_SENDERSis set and the envelope sender isn’t on it, reject it withSender not allowed. - Read the DMARC result. If
REQUIRE_DMARCistrueand the result isn’tpass, reject it withDMARC check failed. - Save the raw email to R2.
- If
FORWARD_TOis set, forward the email to it.
A rejection returns a permanent error to the sending server, which then sends a bounce to the sender. Nothing is stored for a rejected email.
Limits
These limits apply to every email:
| Limit | Value | Set by |
|---|---|---|
| Largest email Email Routing accepts | 25 MiB | Cloudflare |
| Largest email the Worker stores | 20 MiB | MAX_BYTES in worker/src/index.ts |
Metadata envelopeFrom and envelopeTo |
200 characters each | The Worker |
Metadata from and messageId |
300 characters each | The Worker |
Metadata subject |
400 characters | The Worker |
The email itself is always stored whole. Only the copies in the metadata are cut.
Storage format
Each email is one R2 object with this key:
<PREFIX>/<YYYY-MM-DD>/<ISO timestamp>-<UUID>.eml
| Part | Description |
|---|---|
PREFIX |
The PREFIX setting, mail by default |
YYYY-MM-DD |
The arrival date in UTC |
ISO timestamp |
The arrival time in UTC with milliseconds, such as 2026-11-06T21:50:24.407Z |
UUID |
A random universally unique identifier (UUID), so two emails in the same millisecond get different keys |
The object body is the email exactly as Email Routing delivered it, in Multipurpose Internet Mail Extensions (MIME) format. Its content type is message/rfc822.
Object metadata
The Worker attaches these fields to each object as R2 custom metadata. S3 tools show them as x-amz-meta-* headers, in lowercase:
| Field | Description |
|---|---|
received |
When the Worker stored the email, in ISO 8601 UTC |
envelopeFrom |
The envelope sender the sending server gave |
envelopeTo |
The envelope recipient, your routed address |
from |
The From header |
subject |
The Subject header |
messageId |
The Message-ID header |
dmarc |
The DMARC result: pass, fail, none, unknown, or another value from Cloudflare’s header |
Line breaks in header values are replaced with spaces. For what each DMARC value means, see DMARC values.
Setup script options
scripts/setup.sh reads its options from environment variables. Run it from anywhere; it changes to the repo folder first.
| Variable | Default | Description |
|---|---|---|
BUCKET |
r2-mailbox |
The bucket to create. Must match bucket_name in worker/wrangler.jsonc. |
RETENTION_DAYS |
30 |
Days before stored emails are deleted. 0 skips the lifecycle rule. |
ADDRESS |
None | The address to route to the Worker |
ZONE_ID |
None | The zone ID of the domain ADDRESS belongs to |
CLOUDFLARE_API_TOKEN |
None | An API token with Email Routing Rules: Edit on that zone |
CLOUDFLARE_ACCOUNT_ID |
None | Needed only if your login has more than one account |
WRANGLER |
Pinned Wrangler, or npx --yes wrangler@latest |
The Wrangler command to run |
The script runs these steps in order, and stops at the first one that fails:
- Check that
BUCKETmatchesbucket_nameinworker/wrangler.jsonc. - Check that Wrangler is logged in.
- Create the bucket, or reuse it if it exists.
- Unless
RETENTION_DAYSis0, add a lifecycle rule namedexpire-<N>dthat deletes objects undermail/after N days. Errors from this step are ignored. - Deploy the Worker.
- If
ADDRESS,ZONE_ID, andCLOUDFLARE_API_TOKENare all set, check that Email Routing is on for the zone and create a rule that sendsADDRESSto the Worker, unless a rule for that address already exists. - Print the remaining manual steps.
The lifecycle rule always covers mail/, whatever PREFIX is set to. If you change PREFIX, add a rule for the new folder yourself.
npm scripts
package.json defines these scripts:
| Script | Runs | Description |
|---|---|---|
npm run setup |
./scripts/setup.sh |
Create the bucket and lifecycle rule, and deploy |
npm run deploy |
wrangler deploy |
Deploy the Worker with the current config |
npm run tail |
wrangler tail |
Stream the Worker’s live logs |
npm run typecheck |
tsc --noEmit |
Type-check the Worker |
npm run check |
python3 -I reader/mailbox.py check |
Test the reader’s key and bucket access |