Cloudflare Email Workers

Process incoming emails programmatically using Cloudflare Workers runtime.

Overview

Email Workers enable custom email processing logic at the edge. Build spam filters, auto-responders, ticket systems, notification handlers, and more using the same Workers runtime you use for HTTP requests.

Key capabilities:

• Process inbound emails with full message access
• Forward to verified destinations
• Send replies with proper threading
• Parse MIME content and attachments
• Integrate with KV, R2, D1, and external APIs

Quick Start

Minimal ES Modules Handler

  async email(message, env, ctx) {
    // Reject spam
    if (message.from.includes('spam.com')) {
      message.setReject('Blocked');
      return;
    }
    
    // Forward to inbox
    await message.forward('inbox@example.com');
  }
};

Core Operations

Reading Order

For comprehensive understanding, read files in this order:

1. README.md (this file) - Overview and quick start
2. configuration.md - Setup, deployment, bindings
3. api.md - Complete API reference
4. patterns.md - Real-world implementation examples
5. gotchas.md - Critical pitfalls and debugging

In This Reference

Architecture

Incoming Email → Email Routing → Email Worker
                                    ↓
                              Process + Decide
                                    ↓
                    ┌───────────────┼───────────────┐
                    ↓               ↓               ↓
                Forward          Reply          Reject

Event flow:

1. Email arrives at your domain
2. Email Routing matches route (e.g., support@example.com)
3. Bound Email Worker receives ForwardableEmailMessage
4. Worker processes and takes action (forward/reply/reject)
5. Email delivered or rejected based on worker logic

Key Concepts

Envelope vs Headers

• Envelope addresses (message.from, message.to): SMTP transport addresses (trusted)
• Header addresses (parsed from body): Display addresses (can be spoofed)

Use envelope addresses for security decisions.

Single-Use Streams

message.raw is a ReadableStream that can only be read once. Buffer to ArrayBuffer for multiple uses.

// Buffer first
const buffer = await new Response(message.raw).arrayBuffer();
const email = await PostalMime.parse(buffer);

See gotchas.md for details.

Verified Destinations

forward() only works with addresses verified in the Cloudflare Email Routing dashboard. Add destinations before deployment.

Use Cases

• Spam filtering: Block based on sender, content, or reputation
• Auto-responders: Send acknowledgment replies with threading
• Ticket creation: Parse emails and create support tickets
• Email archival: Store in KV, R2, or D1
• Notification routing: Forward to Slack, Discord, or webhooks
• Attachment processing: Extract files to R2 storage
• Multi-tenant routing: Route based on recipient subdomain
• Size filtering: Reject oversized attachments

Limits

See gotchas.md for complete limits table.

Prerequisites

Before deploying Email Workers:

1. Enable Email Routing in Cloudflare dashboard for your domain
2. Verify destination addresses for forwarding
3. Configure DMARC/SPF for sending domains (required for replies)
4. Set up wrangler.jsonc with SendEmail binding

See configuration.md for detailed setup.

Service Worker Syntax (Deprecated)

Modern projects should use ES modules format shown above. Service Worker syntax (addEventListener('email', ...)) is deprecated but still supported.

See Also

• Email Routing Documentation
• Workers Platform
• Wrangler CLI
• postal-mime on npm
• mimetext on npm