cloudflare-email-routing

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
4. This automatically adds MX records, SPF, and DKIM to your DNS
5. Create a destination address:
6. Custom address: hello@yourdomain.com
7. Destination: Your personal email (e.g., you@gmail.com)
8. Verify the destination address via email
9. ✅ 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: Allowlist

Only accept emails from approved senders:

export default {
  async email(message, env, ctx) {
    const allowList = [
      'friend@example.com',
      'coworker@company.com',
      'support@vendor.com',
    ];

    if (!allowList.includes(message.from)) {
      message.setReject('Address not on allowlist');
      return;
    }

    await message.forward('inbox@yourdomain.com');
  },
};

When to use: Contact forms, private email addresses, team inboxes

Pattern 2: Blocklist

Reject emails from specific senders or domains:

export default {
  async email(message, env, ctx) {
    const blockList = [
      'spam@badactor.com',
      '@suspicious-domain.com', // Block entire domain
    ];

    const isBlocked = blockList.some(pattern =>
      message.from.includes(pattern)
    );

    if (isBlocked) {
      message.setReject('Sender blocked');
      return;
    }

    await message.forward('inbox@yourdomain.com');
  },
};

When to use: Spam filtering, blocking harassers, domain-level blocks

Pattern 3: Parse and Store

Extract email content and store in D1 or KV:

import PostalMime from 'postal-mime';

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

    // Store in D1
    await env.DB.prepare(
      'INSERT INTO emails (from_addr, subject, text, received_at) VALUES (?, ?, ?, ?)'
    ).bind(
      message.from,
      email.subject,
      email.text,
      new Date().toISOString()
    ).run();

    // Forward to inbox
    await message.forward('inbox@yourdomain.com');
  },
};

When to use: Email archiving, ticket systems, support inboxes, audit logs

Pattern 4: Auto-Reply

Send automatic replies with custom logic:

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

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

    // Create reply
    const msg = createMimeMessage();
    msg.setSender({ name: 'Support Team', addr: 'support@yourdomain.com' });
    msg.setRecipient(message.from);
    msg.setHeader('In-Reply-To', message.headers.get('Message-ID'));
    msg.setSubject(`Re: ${email.subject}`);
    msg.addMessage({
      contentType: 'text/plain',
      data: `Thank you for your message about "${email.subject}". We'll respond within 24 hours.`,
    });

    // Send reply
    const replyMessage = new EmailMessage(
      'support@yourdomain.com',
      message.from,
      msg.asRaw()
    );

    await message.reply(replyMessage);

    // Also forward to team inbox
    await message.forward('team@yourdomain.com');
  },
};
`