How do you test a Cloudflare Email Worker locally with wrangler dev, and which production checks does the local email simulation skip?
answer
- a local email endpoint
- raw message in, envelope in query
- Message-ID is required
- forwards are logged, not delivered
- no verification, no DMARC
basics
~20 sRun 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.
solid answer
~50 s`wrangler dev` exposes `/cdn-cgi/local/email`. POST the raw message as the body, with the envelope sender and recipient as `from` and `to` query parameters, and the Worker's `email()` handler runs directly. The endpoint answers 400 if a parameter or the `Message-ID` header is missing, or if the message exceeds 25 MiB. It returns *Worker successfully processed email*, or a 400 *Worker rejected email with the following reason: ...* after `setReject()`. Adding `format=json` returns the outcome, the reject reason, each forward and each reply. Locally, `forward()` reaches no inbox and replies are written to `.eml` files. Under Wrangler 4.149.0 the simulation skips several production checks: routing rules, destination verification, SPF, DKIM and DMARC, the `X-` filter on forwarded headers, and the one-reply rule. A `send_email` binding is simulated too: mail is logged and saved to files, and local code sends it for real only when the binding sets `remote: true`.
code
bash · 5 linescurl --request POST 'http://localhost:8787/cdn-cgi/local/email' \
--url-query '[email protected]' \
--url-query '[email protected]' \
--url-query 'format=json' \
--data-binary $'From: "Billing" <[email protected]>\r\nTo: [email protected]\r\nSubject: Invoice 7781\r\nMessage-ID: <[email protected]>\r\nDate: Mon, 26 Oct 2026 10:00:00 +0000\r\n\r\nInvoice attached.\r\n'go deeper
Recall the endpoint /cdn-cgi/local/email, the from and to query parameters, and that the body is the raw message with a Message-ID.
Explain how to read the plain and format=json responses, which reply rules the simulation enforces, and how the send_email binding is simulated.
Name what the simulation skips, such as verification, authentication, header filtering and the one-reply limit, and close those gaps with a real test address and the Activity log before trusting a release.
Decide what the team tests locally, what it proves only against a real domain, and who owns the test mailboxes that a remote binding may reach.
## Triggering the handler locally An Email Worker is invoked by mail, not by HTTP, so local testing needs a stand-in for the SMTP delivery. `wrangler dev` (local mode, the default) provides one: an endpoint at `/cdn-cgi/local/email` on the dev server. A POST to it builds a `ForwardableEmailMessage` and calls the Worker's `email()` handler: - the **body** is the raw message in RFC 5322 form: headers, a blank line, then the body; - the `from` query parameter becomes `message.from`, the envelope sender; - the `to` query parameter becomes `message.to`, the envelope recipient; - the parsed headers become `message.headers`, and the body becomes `message.raw`. With curl, `--url-query` encodes each parameter, so an envelope sender such as `bounces+7781@...` arrives with its plus sign intact. The message must carry a `Message-ID` header. Wrangler warns when `from` differs from the `From` header, or `to` from the `To` header. That warning helps reproduce mail from systems that send with a bounce address. ## Reading the result | Response | Meaning | |---|---| | 200 *Worker successfully processed email* | the handler finished without rejecting | | 400 *Worker rejected email with the following reason: ...* | the handler called `setReject()` | | 400 *... invalid or no message id provided* | the message had no usable `Message-ID` | | 400 for a missing `from`, `to` or body | the request itself was incomplete | | 500 with a stack trace | the handler threw | Append `format=json` to get a structured result instead, with status 200 even when the Worker rejected the message: `outcome`, `rejectReason`, a `forwards` list with each recipient and the headers passed, a `replies` list with each reply's raw MIME, and an `events` timeline. The terminal log shows the same events, and each reply is saved as an `.eml` file. ## What the simulation checks The local run enforces several rules, mostly ones production documents too, so tests catch these: - the **25 MiB** inbound size limit; - a reply's `In-Reply-To` must equal the original `Message-ID`, and a reply without one throws; - a reply's `From` header must match the `EmailMessage` sender; - a reply chain whose `References` header runs to about 100 entries cannot be replied to, as in production, and the simulation also refuses replies to messages marked `Auto-Submitted` (other than `no`); - a `send_email` binding enforces `destination_address`, `allowed_destination_addresses` and `allowed_sender_addresses`. ## What it does not check These were observed with Wrangler 4.149.0 and its local runtime: - **No routing rules.** The endpoint calls the Worker directly with whatever `to` you pass. Dashboard rules, the catch-all and the Wrangler `addresses` field only matter in production. - **No destination verification.** `forward()` to any address succeeds and is only logged. - **No authentication.** Nothing checks SPF, DKIM or DMARC, so a reply that works locally can still throw in production for want of a valid DMARC result. - **No header filter on forward().** A `Subject` header passed to `forward()` shows up in the local log, though production keeps only `X-` headers. - **No one-reply limit.** A second `reply()` in the same event succeeds locally, though production allows one. - **No production error codes.** A `send_email` restriction failure throws a plain message such as *email from [email protected] not allowed*, not one of the documented `E_` codes. ## Testing the sending side By default the `send_email` binding is simulated too. The call is logged, and the text and HTML bodies are saved to local files you can open, while nothing reaches a real inbox. Binary attachments passed as `ArrayBuffer` fail locally with *Cannot serialize value: [object ArrayBuffer]*, so test them against a deployed Worker. Setting `remote: true` on the binding makes local code send real mail through Email Service. Point it only at your own test addresses. ## Closing the gap 1. Keep the routing decision in a plain function, such as which inbox a given `to` and header domain map to, and unit-test it. 2. Use the local endpoint to check the handler's wiring: which action runs, which headers it passes, and what the reply looks like. 3. Before relying on it, send real mail from an outside account to a test address on the onboarded domain, and read the **Activity log** for the routing status and the SPF, DKIM and DMARC results. 4. Watch the first production days for `forward()` or `reply()` failures in the Worker's logs. Failures caused by unverified destinations or missing DMARC can appear only in production, never in a local run.
- Why does the local email endpoint answer 400 for a message pasted from a mail client?The usual causes are a missing `Message-ID` header, a missing `from` or `to` query parameter, a body that is not a parseable RFC 5322 message, or a message over the 25 MiB limit. A 400 that quotes a reason means the Worker itself called `setReject()`.
- How do you test the send_email side locally without mailing real customers?Leave the binding in its default local mode. Each `send()` is logged, and its text and HTML bodies are saved to files you can open. Setting `remote: true` would send real mail through Email Service. `ArrayBuffer` attachments cannot be serialized locally, so test them on a deployed Worker.
- Does a local email test apply your Email Routing rules?No. The endpoint calls the Worker's `email()` handler directly with the `to` you pass. Routing rules, the catch-all and the Wrangler `addresses` field take effect only in production, after `wrangler deploy` for the last of these.
- If forward() succeeds under wrangler dev, the destination address must be verified.
- The local email endpoint applies the dashboard's routing rules and catch-all.
- A reply that works locally will also pass production's DMARC requirement.
- Local send_email calls deliver to the recipient's inbox by default.
- Any raw message works locally; the Message-ID header is optional.
Assumes Wrangler 4.149.0 as pinned on 2026-10-10; the local email simulation has gained checks across releases, so a newer Wrangler may enforce more.