skip to content

Email Routing & Workers

Email Service routes a domain's mail to verified addresses or to an Email Worker, and lets Workers send mail. Interviewers ask how an Email Worker forwards, rejects or replies.

on this pageshow

explore

questions

5

In Cloudflare Email Routing, how do routing rules, the catch-all rule and verified destination addresses deliver a domain's support@ and sales@ mail?

level: juniorimportance: should knowfreq 30%

answer

  1. pattern, action, destination
  2. verify before it forwards
  3. one rule, one destination
  4. catch-all takes the unmatched
  5. Wrangler addresses field reconciles rules

basics

~20 s

Each Email Routing rule maps one address on the domain to an action: send to a verified destination address, send to a Worker, or drop. The catch-all rule takes unmatched addresses, and rules with unverified destinations stay disabled.

solid answer

~40 s

Onboarding the domain to Email Routing (it must use Cloudflare DNS) adds MX, SPF and DKIM records that bring its mail to Cloudflare. Next you add **destination addresses**: Cloudflare emails each one a link, and until the owner selects **Verify email address**, any rule pointing at it stays disabled. Destinations belong to the account, so one verified inbox serves every domain in it. Then each routing rule pairs an **email pattern** such as `support` with an **action**: *Send to an email*, *Send to a Worker* or *Drop*. One rule has one destination, so mailing two staff inboxes takes a Worker that calls `message.forward()` once per destination. The **catch-all rule** takes everything without its own rule, typos included. A domain holds up to 200 rules, and an account up to 200 destination addresses.

code

toml · 4 lines
toml
name = "invoice-handler"
main = "src/index.js"
compatibility_date = "2026-10-01"
addresses = ["[email protected]"]

go deeper

for a junior

Recall the three parts of a routing rule, the three actions, and that a destination must be verified before any rule using it works.

for a middle

Explain why destinations are account-level, why one rule cannot reach two inboxes, how the catch-all and subaddressing change which rule matches, and the per-domain and per-account limits.

for a senior

Show you can run this safely: keep patterns unique, decide what the catch-all does with unknown addresses, and know which rules Wrangler's addresses field owns so a deploy cannot silently delete a hand-made rule.

for a principal

Talk about ownership: whether routing rules live in the dashboard or in a Worker's Wrangler file, who may verify new destinations, and how a team keeps one source of truth.

## What Email Routing does **Email Routing** is the inbound half of Cloudflare **Email Service** (the other half, Email Sending, sends mail from your applications). It receives mail addressed to your domain and decides, address by address, where each message goes. It is a router, not a mailbox host. A routing rule's action relays each message to an inbox you already have, hands it to a Worker, or discards it. To use it, the domain must be on **Cloudflare DNS**. Onboarding the domain under **Compute > Email Service > Email Routing** adds the records that bring mail to Cloudflare: - **MX records** pointing at Cloudflare's routing mail servers; - an **SPF** TXT record (`v=spf1 include:_spf.mx.cloudflare.net ~all`) on the root domain; - a **DKIM** record for the signatures Email Routing adds to forwarded mail. After onboarding, these records are **Locked**, so nobody deletes them from the DNS page by accident. A record can be unlocked when you move to another mail provider. ## Destination addresses and verification A **destination address** is an existing inbox that Email Routing may forward to, for example a staff member's mailbox at another mail provider. You add it under **Destination Addresses**, and Cloudflare sends it a verification email. The address is usable only after its owner selects **Verify email address**. Until then, every routing rule that points at it stays disabled. This is deliberate. Without it, anyone could make Cloudflare relay mail to a stranger's inbox. Three properties are worth remembering: - destination addresses are **account-level**, so one verified address can serve every domain in the account; - **deleting** a destination address disables every rule that uses it; - an account can hold up to **200** destination addresses. ## Routing rules and their actions A **routing rule** pairs an **email pattern** (the local part, such as `support`, on a chosen domain) with an **action** and a destination. For a small company, `support@` and `sales@` each get one rule pointing at a staff inbox. `invoices@` can point at a Worker that processes the mail. | Action | What happens to a matching message | |---|---| | Send to an email | Forwarded to one verified destination address | | Send to a Worker | Passed to that Worker's `email()` handler | | Drop | Discarded without being routed anywhere | The rules behind that table: 1. **One rule, one destination.** To deliver `support@` mail to two inboxes, route the address to a Worker that calls `message.forward()` once per verified destination. 2. **Patterns should be unique.** If two rules share a pattern, only the one shown first in the dashboard list processes mail. 3. **Rules can be paused.** A rule toggled to **Disabled** stops routing without being deleted. 4. **Renaming a Worker breaks its rules.** The rules lose their link to the Worker and must be edited to point at the new name. A domain can hold up to **200** routing rules. ## The catch-all rule and subaddressing The **catch-all rule** applies when no other rule matches. That covers misspellings such as `ifno@` for `info@`, and addresses nobody planned for. It takes the same actions as any rule. Pointing it at **Drop** makes unknown addresses go nowhere. Pointing it at a Worker lets code decide. **Subaddressing** (plus addressing, RFC 5233) is a setting under **Email Routing > Settings**. When it is on, mail to `[email protected]` matches the `sales@` rule. The `+web` part is kept in `message.to`, so a Worker can still read it. A rule written for the exact subaddress wins over the base rule. ## Managing rules as code Rules can be made in the dashboard, through the Email Routing REST API, or from Wrangler. The `wrangler email routing` commands (for example `wrangler email routing rules create` and `wrangler email routing addresses create`) manage rules and destination addresses directly. From Wrangler 4.113.0, a Worker's configuration file can also carry a top-level `addresses` field, such as `["[email protected]"]`. Each entry becomes a *Send to a Worker* rule for the Worker being deployed, and a `*@example.com` entry sets the catch-all rule (apex domains only). `wrangler deploy` reconciles the list: it adds new rules, updates the ones it manages, and removes managed rules that are no longer listed. It asks before a destructive change. Leaving the field out changes nothing, while an empty array removes every rule that Worker manages. ## Common mistakes - Expecting a rule to work before its destination is verified. - Adding the same destination again for each domain, when the address already serves the whole account. - Creating two rules for one pattern to reach two inboxes. - Leaving the catch-all rule on for an inbox that then fills with mail to random addresses.

  • What happens if two Email Routing rules use the same email pattern?
    Only the rule shown first in the dashboard list processes incoming mail; the other never sees it. Cloudflare's guidance is simply not to create duplicate patterns. If the goal was two inboxes, use one rule that sends to a Worker and have the Worker call `message.forward()` for each verified destination.
  • How do you deliver every support@ message to two staff inboxes?
    Point the `support` rule at a Worker instead of an email destination. In its `email()` handler, call `message.forward()` once per inbox, for example inside `Promise.all`. Both inboxes must already be verified destination addresses in the account, otherwise the forward fails.
  • What does a Worker's Wrangler `addresses` field do to existing Email Routing rules?
    Each entry becomes a *Send to a Worker* rule for that Worker, and `*@domain` sets the apex catch-all. `wrangler deploy` adds, updates and removes only the rules it manages. It asks before deleting or taking over a rule. In a non-interactive run it skips destructive changes and exits with an error after deploying the Worker. Omitting the field leaves rules alone, and `[]` removes every rule the Worker manages.

  • A routing rule forwards as soon as you type in a destination address.
  • Destination addresses must be added and verified again for every domain.
  • One routing rule can forward each message to several inboxes.
  • Email Routing works on any DNS provider once the MX records point at Cloudflare.
  • With subaddressing on, the +detail part is stripped before a Worker sees message.to.

Assumes Email Service as of 2026-10-10: Email Routing joined the new Email Service on 2026-04-16, and the Wrangler addresses field arrived on 2026-09-04 with Wrangler 4.113.0.

open as a page

How does a Cloudflare Worker send order confirmations through Email Service's send_email binding, and what do its restrictions and plan limits change?

level: middleimportance: should knowfreq 30%

basics

~20 s

Declare a send_email binding and call env.EMAIL.send() with from, to, subject and html or text; it resolves to a messageId. Mailing customers needs an onboarded sending domain and the Workers Paid plan; verified destination addresses are free on every plan.

open as a page

In a Cloudflare Email Worker, what do message.forward(), message.setReject() and message.reply() each do inside the email() handler?

level: middleimportance: should knowfreq 30%

basics

~20 s

An Email Worker's email(message, env, ctx) handler gets the incoming message. message.forward() relays it to a verified destination, message.setReject() sends a permanent SMTP error back to the sending server, and message.reply() sends one threaded reply to the original sender.

open as a page

A Cloudflare Email Worker for invoices@ allowlists vendors by message.from and calls setReject() for the rest, yet one vendor's invoices bounce; why, and how do you fix it?

level: seniorimportance: should knowfreq 20%

basics

~20 s

message.from is the envelope MAIL FROM, and a vendor's billing platform often sends with its own bounce address, so an exact allowlist on it rejects real invoices. Compare the domain of the From header instead, and log decisions before enforcing setReject().

open as a page

How do you test a Cloudflare Email Worker locally with wrangler dev, and which production checks does the local email simulation skip?

level: middleimportance: nice to knowfreq 20%

basics

~20 s

Run wrangler dev and POST a raw RFC 5322 message with a Message-ID header to /cdn-cgi/local/email, passing the envelope from and to as query parameters. The Worker's forward(), setReject() and reply() calls are logged; nothing is verified or delivered.

open as a page