Cloudflare Email Routing

Status: Production Ready ✅ Last Updated: 2025-10-23 Latest Versions: postal-mime@2.5.0, mimetext@3.0.27

---

What is Cloudflare Email Routing?

Cloudflare Email Routing provides two complementary capabilities:

1. Email Workers - Receive and process incoming emails with custom logic (allowlists, blocklists, forwarding, parsing, replying)
2. Send Email - Send emails from Workers to verified destination addresses (notifications, alerts, confirmations)

Both capabilities are free and work together to enable complete email functionality in Cloudflare Workers.

---

Quick Start (10 Minutes)

Part 1: Enable Email Routing (Dashboard)

Prerequisites: Domain must be on Cloudflare DNS

1. Log in to Cloudflare Dashboard → select your domain
2. Go to Email > Email Routing
3. Select Enable Email Routing → Add records and enable
   • This automatically adds MX records, SPF, and DKIM to your DNS
4. Create a destination address:
   • Custom address: hello@yourdomain.com
   • Destination: Your personal email (e.g., you@gmail.com)
   • Verify the destination address via email
5. ✅ Basic email forwarding is now active

What you just did: Configured DNS and basic forwarding. Now let's add Workers for custom logic.

---

Part 2: Receiving Emails with Email Workers

1. Install Dependencies

npm install postal-mime@2.5.0 mimetext@3.0.27

Why these packages:

• postal-mime - Parse incoming email messages (headers, body, attachments)
• mimetext - Create email messages for sending/replying

2. Create Email Worker

Create src/email.ts:

import { EmailMessage } from 'cloudflare:email';
import PostalMime from 'postal-mime';

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

    console.log('From:', message.from);
    console.log('To:', message.to);
    console.log('Subject:', email.subject);

    // Forward to verified destination
    await message.forward('your-email@example.com');
  },
};

3. Configure Wrangler

Update wrangler.jsonc:

{
  "name": "email-worker",
  "main": "src/email.ts",
  "compatibility_date": "2025-10-11"
}

4. Deploy and Bind

npx wrangler deploy

# In Cloudflare Dashboard:
# Email > Email Routing > Email Workers
# Select your worker → Create route → Enter address (e.g., hello@yourdomain.com)

What you just did: Created a Worker that logs and forwards emails.

---

Part 3: Sending Emails from Workers

1. Configure Send Email Binding

Update wrangler.jsonc:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "send_email": [
    {
      "name": "EMAIL",
      "destination_address": "notifications@yourdomain.com"
    }
  ]
}

CRITICAL: destination_address must be:

• A domain where you have Email Routing enabled
• A verified destination address in Email Routing settings

2. Send Email from Worker

import { EmailMessage } from 'cloudflare:email';
import { createMimeMessage } from 'mimetext';

export default {
  async fetch(request, env, ctx) {
    // Create email message
    const msg = createMimeMessage();
    msg.setSender({ name: 'My App', addr: 'noreply@yourdomain.com' });
    msg.setRecipient('user@example.com');
    msg.setSubject('Welcome to My App');
    msg.addMessage({
      contentType: 'text/plain',
      data: 'Thank you for signing up!',
    });

    // Send via binding
    const message = new EmailMessage(
      'noreply@yourdomain.com',
      'user@example.com',
      msg.asRaw()
    );

    await env.EMAIL.send(message);

    return new Response('Email sent!');
  },
};

3. Deploy

npx wrangler deploy

What you just did: Configured your Worker to send emails to verified addresses.

---

Email Workers: Complete Guide

Runtime API

EmailEvent Handler

export default {
  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {
    // Process email here
  },
};

Parameters:

• message - ForwardableEmailMessage object
• env - Environment bindings (KV, D1, secrets, etc.)
• ctx - Execution context (waitUntil for async operations)

ForwardableEmailMessage Properties

interface ForwardableEmailMessage {
  readonly from: string;          // Sender email
  readonly to: string;            // Recipient email
  readonly headers: Headers;      // Email headers
  readonly raw: ReadableStream;   // Raw email message
  readonly rawSize: number;       // Size in bytes

  // Methods
  setReject(reason: string): void;
  forward(rcptTo: string, headers?: Headers): Promise<void>;
  reply(message: EmailMessage): Promise<void>;
}

---

Common Patterns

Pattern 1: All

...