openai-cloudflare-deploy/references/email-routing/README.md

Cloudflare Email Routing Skill Reference

Overview

Cloudflare Email Routing enables custom email addresses for your domain that route to verified destination addresses. It's free, privacy-focused (no storage/access), and includes Email Workers for programmatic email processing.

Available to all Cloudflare customers using Cloudflare as authoritative nameserver.

Quick Start

// Basic email handler
export default {
  async email(message, env, ctx) {
    // CRITICAL: Must consume stream before response
    const parser = new PostalMime.default();
    const email = await parser.parse(await message.raw.arrayBuffer());

    // Process email
    console.log(`From: ${message.from}, Subject: ${email.subject}`);

    // Forward or reject
    await message.forward("[email protected]");
  }
} satisfies ExportedHandler<Env>;

Reading Order

Start here based on your goal:

1. New to Email Routing? → configuration.md → patterns.md
2. Adding Workers? → api.md § Worker Runtime API → patterns.md
3. Sending emails? → api.md § SendEmail Binding
4. Managing via API? → api.md § REST API Operations
5. Debugging issues? → gotchas.md

Decision Tree

Need to receive emails?
├─ Simple forwarding only? → Dashboard rules (configuration.md)
├─ Complex logic/filtering? → Email Workers (api.md + patterns.md)
└─ Parse attachments/body? → postal-mime library (patterns.md § Parse Email)

Need to send emails?
├─ From Worker? → SendEmail binding (api.md § SendEmail)
└─ From external app? → Use external SMTP/API service

Having issues?
├─ Email not arriving? → gotchas.md § Mail Authentication
├─ Worker crashing? → gotchas.md § Stream Consumption
└─ Forward failing? → gotchas.md § Destination Verification

Key Concepts

Routing Rules: Pattern-based forwarding configured via Dashboard/API. Simple but limited.

Email Workers: Custom TypeScript handlers with full email access. Handles complex logic, parsing, storage, rejection.

SendEmail Binding: Outbound email API for Workers. Transactional email only (no marketing/bulk).

ForwardableEmailMessage: Runtime interface for incoming emails. Provides headers, raw stream, forward/reject methods.

In This Reference

• configuration.md - Setup, deployment, wrangler config
• api.md - REST API + Worker runtime API + types
• patterns.md - Common patterns with working examples
• gotchas.md - Critical pitfalls, troubleshooting, limits

Architecture

Internet → MX Records → Cloudflare Email Routing
                            ├─ Routing Rules (dashboard)
                            └─ Email Worker (your code)
                                ├─ Forward to destination
                                ├─ Reject with reason
                                ├─ Store in R2/KV/D1
                                └─ Send outbound (SendEmail)

See Also

• Cloudflare Docs: Email Routing
• Cloudflare Docs: Email Workers
• postal-mime npm package