1# Cloudflare Email Workers
2 
3Process incoming emails programmatically using Cloudflare Workers runtime.
4 
5## Overview
6 
7Email 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.
8 
9**Key capabilities**:
10- Process inbound emails with full message access
11- Forward to verified destinations
12- Send replies with proper threading
13- Parse MIME content and attachments
14- Integrate with KV, R2, D1, and external APIs
15 
16## Quick Start
17 
18### Minimal ES Modules Handler
19 
20```typescript
21export default {
22  async email(message, env, ctx) {
23    // Reject spam
24    if (message.from.includes('spam.com')) {
25      message.setReject('Blocked');
26      return;
27    }
28    
29    // Forward to inbox
30    await message.forward('[email protected]');
31  }
32};
33```
34 
35### Core Operations
36 
37| Operation | Method | Use Case |
38|-----------|--------|----------|
39| Forward | `message.forward(to, headers?)` | Route to verified destination |
40| Reject | `message.setReject(reason)` | Block with SMTP error |
41| Reply | `message.reply(emailMessage)` | Auto-respond with threading |
42| Parse | postal-mime library | Extract subject, body, attachments |
43 
44## Reading Order
45 
46For comprehensive understanding, read files in this order:
47 
481. **README.md** (this file) - Overview and quick start
492. **configuration.md** - Setup, deployment, bindings
503. **api.md** - Complete API reference
514. **patterns.md** - Real-world implementation examples
525. **gotchas.md** - Critical pitfalls and debugging
53 
54## In This Reference
55 
56| File | Description | Key Topics |
57|------|-------------|------------|
58| [api.md](./api.md) | Complete API reference | ForwardableEmailMessage, SendEmail bindings, reply() method, postal-mime/mimetext APIs |
59| [configuration.md](./configuration.md) | Setup and configuration | wrangler.jsonc, bindings, deployment, dependencies |
60| [patterns.md](./patterns.md) | Real-world examples | Allowlists from KV, auto-reply with threading, attachment extraction, webhook notifications |
61| [gotchas.md](./gotchas.md) | Pitfalls and debugging | Stream consumption, ctx.waitUntil errors, security, limits |
62 
63## Architecture
64 
65```
66Incoming Email → Email Routing → Email Worker
67                                    ↓
68                              Process + Decide
69                                    ↓
70                    ┌───────────────┼───────────────┐
71                    ↓               ↓               ↓
72                Forward          Reply          Reject
73```
74 
75**Event flow**:
761. Email arrives at your domain
772. Email Routing matches route (e.g., `[email protected]`)
783. Bound Email Worker receives `ForwardableEmailMessage`
794. Worker processes and takes action (forward/reply/reject)
805. Email delivered or rejected based on worker logic
81 
82## Key Concepts
83 
84### Envelope vs Headers
85 
86- **Envelope addresses** (`message.from`, `message.to`): SMTP transport addresses (trusted)
87- **Header addresses** (parsed from body): Display addresses (can be spoofed)
88 
89Use envelope addresses for security decisions.
90 
91### Single-Use Streams
92 
93`message.raw` is a ReadableStream that can only be read once. Buffer to ArrayBuffer for multiple uses.
94 
95```typescript
96// Buffer first
97const buffer = await new Response(message.raw).arrayBuffer();
98const email = await PostalMime.parse(buffer);
99```
100 
101See [gotchas.md](./gotchas.md#readablestream-can-only-be-consumed-once) for details.
102 
103### Verified Destinations
104 
105`forward()` only works with addresses verified in the Cloudflare Email Routing dashboard. Add destinations before deployment.
106 
107## Use Cases
108 
109- **Spam filtering**: Block based on sender, content, or reputation
110- **Auto-responders**: Send acknowledgment replies with threading
111- **Ticket creation**: Parse emails and create support tickets
112- **Email archival**: Store in KV, R2, or D1
113- **Notification routing**: Forward to Slack, Discord, or webhooks
114- **Attachment processing**: Extract files to R2 storage
115- **Multi-tenant routing**: Route based on recipient subdomain
116- **Size filtering**: Reject oversized attachments
117 
118## Limits
119 
120| Limit | Value |
121|-------|-------|
122| Max message size | 25 MiB |
123| Max routing rules | 200 |
124| Max destinations | 200 |
125| CPU time (free tier) | 10ms |
126| CPU time (paid tier) | 30s (default), 5min (max) |
127 
128See [gotchas.md](./gotchas.md#limits-reference) for complete limits table.
129 
130## Prerequisites
131 
132Before deploying Email Workers:
133 
1341. **Enable Email Routing** in Cloudflare dashboard for your domain
1352. **Verify destination addresses** for forwarding
1363. **Configure DMARC/SPF** for sending domains (required for replies)
1374. **Set up wrangler.jsonc** with SendEmail binding
138 
139See [configuration.md](./configuration.md) for detailed setup.
140 
141## Service Worker Syntax (Deprecated)
142 
143Modern projects should use ES modules format shown above. Service Worker syntax (`addEventListener('email', ...)`) is deprecated but still supported.
144 
145## See Also
146 
147- [Email Routing Documentation](https://developers.cloudflare.com/email-routing/)
148- [Workers Platform](https://developers.cloudflare.com/workers/)
149- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
150- [postal-mime on npm](https://www.npmjs.com/package/postal-mime)
151- [mimetext on npm](https://www.npmjs.com/package/mimetext)
152