Email Workers local development

Author: celso

src/content/docs/email-routing/email-workers/demos.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Demos
 sidebar:
-  order: 6
+  order: 7
 
 ---
 
@@ -14,4 +14,4 @@ Learn how you can use Email Workers within your existing architecture.
 
 Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Email Workers.
 
-<ExternalResources type="apps" products={["Email Workers"]} />
+<ExternalResources type="apps" products={["Email Workers"]} />

src/content/docs/email-routing/email-workers/local-development.mdx

@@ -0,0 +1,214 @@
+---
+title: Local Development
+sidebar:
+  order: 6
+  badge: Beta
+
+---
+
+import { Render, Type, MetaInfo, WranglerConfig } from "~/components";
+
+You can test the behavior of your `email()` handler in local development using [wrangler dev](/workers/wrangler/commands/#dev).
+
+Right now local development for Email Workers is in beta. To use it, you need to install a preview release of Wrangler.
+
+```bash
+npm install --save-dev https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/14106373814/npm-package-wrangler-8375
+```
+
+Make sure you have Email Routing [enabled](/email-routing/get-started/enable-email-routing/), at least one verified [destination address](/email-routing/setup/email-routing-addresses/#destination-addresses), and your wrangler configuration declares the Email Workers binding:
+
+<WranglerConfig>
+
+```jsonc
+{
+	"dev": {
+		"port": 8787,
+    "local_protocol": "http"
+	},
+  "send_email": [
+    {
+      "name": "EMAIL"
+    }
+  ]
+}
+```
+
+</WranglerConfig>
+
+You can now test receiving, replying and sending emails in your local environment.
+
+## Receiving an email
+
+Consider this example Email Worker script that uses the opensource [postal-mime](https://www.npmjs.com/package/postal-mime) email parser:
+
+```ts
+import * as PostalMime from 'postal-mime';
+
+export default {
+
+	async email(message, env: any, ctx: any) {
+		const parser = new PostalMime.default();
+		const rawEmail = new Response(message.raw);
+		const email = await parser.parse(await rawEmail.arrayBuffer());
+		console.log(email);
+	},
+
+};
+```
+
+Now when you run `npx wrangler dev`, wrangler will will expose a local `/cdn-cgi/handler/email` endpoint that you can `POST` email messages to and trigger your Worker script `email()` handler:
+
+```bash
+curl -X POST 'http://localhost:8787/cdn-cgi/handler/email' \
+  --url-query '[email protected]' \
+  --url-query '[email protected]' \
+  --header 'Content-Type: application/json' \
+  --data-raw 'Received: from smtp.example.com (127.0.0.1)
+        by cloudflare-email.com (unknown) id 4fwwffRXOpyR
+        for <[email protected]>; Tue, 27 Aug 2024 15:50:20 +0000
+From: "John" <[email protected]>
+Reply-To: [email protected]
+To: [email protected]
+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'
+```
+
+This is what you get in the console:
+
+```json
+{
+  headers: [
+    {
+      key: 'received',
+      value: 'from smtp.example.com (127.0.0.1) by cloudflare-email.com (unknown) id 4fwwffRXOpyR for <[email protected]>; Tue, 27 Aug 2024 15:50:20 +0000'
+    },
+    { key: 'from', value: '"John" <[email protected]>' },
+    { key: 'reply-to', value: '[email protected]' },
+    { key: 'to', value: '[email protected]' },
+    { 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: '[email protected]', name: 'John' },
+  to: [ { address: '[email protected]', name: '' } ],
+  replyTo: [ { address: '[email protected]', name: '' } ],
+  subject: 'Testing Email Workers Local Dev',
+  messageId: '<6114391943504294873000@ZSH-GHOSTTY>',
+  date: '2024-08-27T15:49:44.000Z',
+  html: 'Hi there\n',
+  attachments: []
+}
+```
+
+## Sending an email
+
+Wrangler can also simulate sending emails locally. Consider this example Email Worker script that uses the [mimetext](https://www.npmjs.com/package/mimetext) npm package:
+
+```ts
+import { EmailMessage } from "cloudflare:email";
+import { createMimeMessage } from 'mimetext';
+
+export default {
+
+	async fetch(request, env, ctx) {
+		const msg = createMimeMessage();
+		msg.setSender({ name: 'Sending email test', addr: '[email protected]' });
+		msg.setRecipient('[email protected]');
+		msg.setSubject('An email generated in a worker');
+		msg.addMessage({
+			contentType: 'text/plain',
+			data: `Congratulations, you just sent an email from a worker.`,
+		});
+
+		var message = new EmailMessage('[email protected]', '[email protected]', msg.asRaw());
+		await env.EMAIL.send(message);
+		return Response.json({ ok: true });
+	}
+
+};
+```
+
+Now when you run `npx wrangler dev`, go to http://localhost:8787/ to trigger the `fetch()` handler and send the email. You will see the follow message in your terminal:
+
+```bash
+[wrangler:inf] GET / 200 OK (19ms)
+send_email binding called with the following message:
+/var/folders/33/pn86qymd0w50htvsjp93rys40000gn/T/miniflare-25d0146a88267bfc8d4b91b42ad5a4d0/files/28318e5d-d1c8-4bf6-b2c1-9dcb40088391.eml
+```
+
+Wrangler simulated `env.EMAIL.send()` by writing the email to a local file in [eml](https://datatracker.ietf.org/doc/html/rfc822). The file contains the raw email message:
+
+```
+Date: Fri, 04 Apr 2025 12:27:08 +0000
+From: =?utf-8?B?U2VuZGluZyBlbWFpbCB0ZXN0?= <[email protected]>
+To: <[email protected]>
+Message-ID: <[email protected]>
+Subject: =?utf-8?B?QW4gZW1haWwgZ2VuZXJhdGVkIGluIGEgd29ya2Vy?=
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 7bit
+
+Congratulations, you just sent an email from a worker.
+```
+
+## Replying to and forwarding messages
+
+Likewise, [`EmailMessage`](/email-routing/email-workers/runtime-api/#emailmessage-definition)'s `forward()` and `reply()` methods are also simulated locally. Consider this Worker that receives an email, parses it, replies to the sender, and forwards the original message to one your verified recipient addresses:
+
+```ts
+import * as PostalMime from 'postal-mime';
+import { createMimeMessage } from 'mimetext';
+import { EmailMessage } from 'cloudflare:email';
+
+export default {
+	async email(message, env: any, ctx: any) {
+		// parses incoming message
+		const parser = new PostalMime.default();
+		const rawEmail = new Response(message.raw);
+		const email = await parser.parse(await rawEmail.arrayBuffer());
+
+		// creates some ticket
+		// const ticket = await createTicket(email);
+
+		// creates reply message
+		const msg = createMimeMessage();
+		msg.setSender({ name: 'Thank you for your contact', addr: '[email protected]' });
+		msg.setRecipient(message.from);
+		msg.setHeader('In-Reply-To', message.headers.get('Message-ID'));
+		msg.setSubject('An email generated in a worker');
+		msg.addMessage({
+			contentType: 'text/plain',
+			data: `This is an automated reply. We received you email with the subject "${email.subject}", and will handle it as soon as possible.`,
+		});
+
+		var replyMessage = new EmailMessage('[email protected]', message.from, msg.asRaw());
+
+		await message.reply(replyMessage);
+		await message.forward("[email protected]");
+	},
+};
+```
+
+Run `npx wrangler dev` and use curl to POST the same message from the [Receiving an email](#receiving-an-email) example. Your terminal will show you where to find the replied message in your local disk and to whom the email was forwarded:
+
+```bash
+[wrangler:inf] Ready on http://localhost:8787
+⎔ Starting local server...
+.reply() called from Email Handler with the following message:
+/var/folders/33/pn86qymd0w50htvsjp93rys40000gn/T/miniflare-9deb89ed3538650182911d0c23676206/files/935d333b-3850-4d3b-b042-4d3b9b53469c.eml
+.forward() called from Email Handler with
+rcptTo: [email protected]
+```
+
+Note that Email Workers local development is still in beta and requires a preview version of wrangler. This page will update when we merge it into the main branch.

src/content/docs/email-routing/email-workers/runtime-api.mdx

@@ -17,8 +17,8 @@ An `EmailEvent` is the event type to programmatically process your emails with a
 `EmailEvent` can be handled in Workers functions written using the Service Worker syntax by attaching to the `email` event with `addEventListener`:
 
 ```js
-addEventListener("email", (event) => {
-  event.message.forward("<YOUR_EMAIL>");
+addEventListener("email", async (event) => {
+  await event.message.forward("<YOUR_EMAIL>");
 });
 ```
 
@@ -41,7 +41,7 @@ addEventListener("email", (event) => {
 ```js
 export default {
   async email(message, env, ctx) {
-    message.forward("<YOUR_EMAIL>");
+    await message.forward("<YOUR_EMAIL>");
   },
 };
 ```
@@ -118,4 +118,3 @@ export default {
 
   * Reply to the sender of this email message with a new EmailMessage object.
   * When the promise resolves, the message is confirmed to be replied.
-

src/content/glossary/fundamentals.yaml

@@ -112,7 +112,7 @@ entries:
   - term: protocol
     general_definition: |-
       a protocol is a set of rules governing the exchange or transmission of data between devices.
-  
+
   - term: proxy server
     general_definition: |-
       the server that sits between the origin server and the client. Cloudflare is a proxy server for example.

src/content/learning-paths/china-network-overview.json

@@ -2,7 +2,7 @@
 	"title": "Introduction to the China Network",
 	"path": "/learning-paths/china-network-overview/series/china-network-main-features-1/",
 	"priority": 1,
-	"description":"Watch to learn how Cloudflare's China Network can help you improve performance, compliance, and connectivity for your users in mainland China.",
+	"description": "Watch to learn how Cloudflare's China Network can help you improve performance, compliance, and connectivity for your users in mainland China.",
 	"products": ["China Network"],
 	"product_group": "Application performance",
 	"additional_groups": ["Application security"],

src/content/learning-paths/durable-objects-course.json

@@ -2,7 +2,7 @@
 	"title": "Introduction to Durable Objects",
 	"path": "/learning-paths/durable-objects-course/series/introduction-to-series-1/",
 	"priority": 2,
-	"description":"Dive into a hands-on Durable Objects project and learn how to build stateful apps using serverless architecture",
+	"description": "Dive into a hands-on Durable Objects project and learn how to build stateful apps using serverless architecture",
 	"products": ["Durable Objects", "Workers"],
 	"product_group": "Developer platform",
 	"video": true

src/content/release-notes/api-deprecations.yaml

@@ -5,7 +5,6 @@ productLink: "/fundamentals/"
 productArea: Core platform
 productAreaLink: /fundamentals/reference/changelog/platform/
 entries:
-
   - publish_date: "2025-03-20"
     title: "Cloudflare Radar: Attack top industry and vertical endpoints"
     description: |-