Skip to content

Test email routing locally

Test email routing Workers locally using wrangler dev with simulated incoming emails

Last updated View as MarkdownAgent setup

Test email routing behavior locally using wrangler dev to simulate incoming emails and verify your routing logic before deploying.

Prerequisites

  1. Sign up for a Cloudflare account ↗︎.
  2. Install Node.js ↗︎.

Node.js version manager

Use Vite+ (vp env) ↗︎ to install and manage Node.js versions.

For supported Node.js versions, refer to the Wrangler system requirements.

Configuration

Configure your Wrangler file:

{
	"name": "email-routing-worker",
	// Set this to today's date
	"compatibility_date": "2026-10-15",
}
name = "email-routing-worker"
# Set this to today's date
compatibility_date = "2026-10-15"

Basic routing worker

import * as PostalMime from "postal-mime";

export default {
	async email(message, env, ctx) {
		// Parse the raw email message
		const parser = new PostalMime.default();
		const rawEmail = new Response(message.raw);
		const email = await parser.parse(await rawEmail.arrayBuffer());

		console.log("Received email:", {
			from: message.from,
			to: message.to,
			subject: email.subject,
			text: email.text,
			html: email.html,
		});

		// Route based on recipient
		if (message.to.includes("support@")) {
			await message.forward("support-team@example.com");
		} else {
			await message.forward("general@example.com");
		}
	},
};

Send a test email

Start your development server:

npx wrangler dev

Send a test email using the local endpoint. The request body must be a raw email message in RFC 5322 ↗︎ format, and the message must include a Message-ID header:

curl --request POST 'http://localhost:8787/cdn-cgi/local/email' \
  --url-query 'from=sender@example.com' \
  --url-query 'to=recipient@example.com' \
  --data-raw 'Received: from smtp.example.com (127.0.0.1)
        by cloudflare-email.com (unknown) id 4fwwffRXOpyR
        for <recipient@example.com>; Tue, 27 Aug 2024 15:50:20 +0000
From: "John" <sender@example.com>
Reply-To: sender@example.com
To: recipient@example.com
Subject: Testing Email Workers Local Dev
Content-Type: text/html; charset="windows-1252"
X-Mailer: Curl
Date: Tue, 27 Aug 2024 08:49:44 -0700
Message-ID: <6114391943504294873000@ZSH-GHOSTTY>

Hi there'

The console shows the parsed email structure:

{
	"headers": [
		{
			"key": "received",
			"value": "from smtp.example.com (127.0.0.1) by cloudflare-email.com (unknown) id 4fwwffRXOpyR for <recipient@example.com>; Tue, 27 Aug 2024 15:50:20 +0000"
		},
		{ "key": "from", "value": "\"John\" <sender@example.com>" },
		{ "key": "reply-to", "value": "sender@example.com" },
		{ "key": "to", "value": "recipient@example.com" },
		{ "key": "subject", "value": "Testing Email Workers Local Dev" },
		{ "key": "content-type", "value": "text/html; charset=\"windows-1252\"" },
		{ "key": "x-mailer", "value": "Curl" },
		{ "key": "date", "value": "Tue, 27 Aug 2024 08:49:44 -0700" },
		{
			"key": "message-id",
			"value": "<6114391943504294873000@ZSH-GHOSTTY>"
		}
	],
	"from": { "address": "sender@example.com", "name": "John" },
	"to": [{ "address": "recipient@example.com", "name": "" }],
	"replyTo": [{ "address": "sender@example.com", "name": "" }],
	"subject": "Testing Email Workers Local Dev",
	"messageId": "<6114391943504294873000@ZSH-GHOSTTY>",
	"date": "2024-08-27T15:49:44.000Z",
	"html": "Hi there\n",
	"attachments": []
}

Next steps

Was this helpful?