cloudflare-email-routing

What this skill does

# Cloudflare Email Routing

**Status**: Production Ready ✅
**Last Updated**: 2025-10-23
**Latest Versions**: [email protected], [email protected]

---

## 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**: `[email protected]`
   - **Destination**: Your personal email (e.g., `[email protected]`)
   - **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

```bash
npm install [email protected] [email protected]
```

**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`:

```typescript
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('[email protected]');
  },
};
```

#### 3. Configure Wrangler

Update `wrangler.jsonc`:

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

#### 4. Deploy and Bind

```bash
npx wrangler deploy

# In Cloudflare Dashboard:
# Email > Email Routing > Email Workers
# Select your worker → Create route → Enter address (e.g., [email protected])
```

**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`:

```jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "send_email": [
    {
      "name": "EMAIL",
      "destination_address": "[email protected]"
    }
  ]
}
```

**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

```typescript
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: '[email protected]' });
    msg.setRecipient('[email protected]');
    msg.setSubject('Welcome to My App');
    msg.addMessage({
      contentType: 'text/plain',
      data: 'Thank you for signing up!',
    });

    // Send via binding
    const message = new EmailMessage(
      '[email protected]',
      '[email protected]',
      msg.asRaw()
    );

    await env.EMAIL.send(message);

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

#### 3. Deploy

```bash
npx wrangler deploy
```

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

---

## Email Workers: Complete Guide

### Runtime API

#### EmailEvent Handler

```typescript
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

```typescript
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:

```typescript
export default {
  async email(message, env, ctx) {
    const allowList = [
      '[email protected]',
      '[email protected]',
      '[email protected]',
    ];

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

    await message.forward('[email protected]');
  },
};
```

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

---

### Pattern 2: Blocklist

Reject emails from specific senders or domains:

```typescript
export default {
  async email(message, env, ctx) {
    const blockList = [
      '[email protected]',
      '@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('[email protected]');
  },
};
```

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

---

### Pattern 3: Parse and Store

Extract email content and store in D1 or KV:

```typescript
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('[email protected]');
  },
};
```

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

---

### Pattern 4: Auto-Reply

Send automatic replies with custom logic:

```typescript
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: '[email protected]' });
    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(
      '[email protected]',
      message.from,
      msg.asRaw()
    );

    await message.reply(replyMessage);

    // Also forward to team inbox
    await message.forward('[email protected]');
  },
};