1# Email Routing API Reference
2 
3## Worker Runtime API
4 
5### Email Handler Interface
6 
7```typescript
8interface ExportedHandler<Env = unknown> {
9  email?(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): void | Promise<void>;
10}
11```
12 
13### ForwardableEmailMessage
14 
15Main interface for incoming emails:
16 
17```typescript
18interface ForwardableEmailMessage {
19  readonly from: string;          // Envelope sender (e.g., "[email protected]")
20  readonly to: string;             // Envelope recipient (e.g., "[email protected]")
21  readonly headers: Headers;       // Web API Headers object
22  readonly raw: ReadableStream;    // Raw MIME message stream
23  
24  setReject(reason: string): void;
25  forward(rcptTo: string, headers?: Headers): Promise<void>;
26}
27```
28 
29**Key Properties:**
30 
31| Property | Type | Description |
32|----------|------|-------------|
33| `from` | `string` | Envelope sender (MAIL FROM), not header From |
34| `to` | `string` | Envelope recipient (RCPT TO), not header To |
35| `headers` | `Headers` | Email headers (Subject, From, To, etc.) |
36| `raw` | `ReadableStream` | Raw MIME message (consume once only) |
37 
38**Methods:**
39 
40- `setReject(reason)`: Reject email with bounce message
41- `forward(rcptTo, headers?)`: Forward to verified destination, optionally add headers
42 
43### Headers Object
44 
45Standard Web API Headers interface:
46 
47```typescript
48// Access headers
49const subject = message.headers.get("subject");
50const from = message.headers.get("from");
51const messageId = message.headers.get("message-id");
52 
53// Check spam score
54const spamScore = parseFloat(message.headers.get("x-cf-spamh-score") || "0");
55if (spamScore > 5) {
56  message.setReject("Spam detected");
57}
58```
59 
60### Common Headers
61 
62`subject`, `from`, `to`, `x-cf-spamh-score` (spam score), `message-id` (deduplication), `dkim-signature` (auth)
63 
64### Envelope vs Header Addresses
65 
66**Critical distinction:**
67 
68```typescript
69// Envelope addresses (routing, auth checks)
70message.from // "[email protected]" (actual sender)
71message.to   // "[email protected]" (your address)
72 
73// Header addresses (display, user-facing)
74message.headers.get("from") // "Alice <[email protected]>"
75message.headers.get("to")   // "Bob <[email protected]>"
76```
77 
78**Use envelope addresses for:**
79- Authentication/SPF checks
80- Routing decisions
81- Bounce handling
82 
83**Use header addresses for:**
84- Display to users
85- Reply-To logic
86- User-facing filtering
87 
88## SendEmail Binding
89 
90Outbound email API for transactional messages.
91 
92### Configuration
93 
94```jsonc
95// wrangler.jsonc
96{
97  "send_email": [
98    { "name": "EMAIL" }
99  ]
100}
101```
102 
103### TypeScript Types
104 
105```typescript
106interface Env {
107  EMAIL: SendEmail;
108}
109 
110interface SendEmail {
111  send(message: EmailMessage): Promise<void>;
112}
113 
114interface EmailMessage {
115  from: string | { name?: string; email: string };
116  to: string | { name?: string; email: string } | Array<string | { name?: string; email: string }>;
117  subject: string;
118  text?: string;
119  html?: string;
120  headers?: Headers;
121  reply_to?: string | { name?: string; email: string };
122}
123```
124 
125### Send Email Example
126 
127```typescript
128interface Env {
129  EMAIL: SendEmail;
130}
131 
132export default {
133  async fetch(request, env, ctx): Promise<Response> {
134    await env.EMAIL.send({
135      from: { name: "Acme Corp", email: "[email protected]" },
136      to: [
137        { name: "Alice", email: "[email protected]" },
138        "[email protected]"
139      ],
140      subject: "Your order #12345 has shipped",
141      text: "Track your package at: https://track.example.com/12345",
142      html: "<p>Track your package at: <a href='https://track.example.com/12345'>View tracking</a></p>",
143      reply_to: { name: "Support", email: "[email protected]" }
144    });
145    
146    return new Response("Email sent");
147  }
148} satisfies ExportedHandler<Env>;
149```
150 
151### SendEmail Constraints
152 
153- **From address**: Must be on verified domain (your domain with Email Routing enabled)
154- **Volume limits**: Transactional only, no bulk/marketing email
155- **Rate limits**: 100 emails/minute on Free plan, higher on Paid
156- **No attachments**: Use links to hosted files instead
157- **No DKIM control**: Cloudflare signs automatically
158 
159## REST API Operations
160 
161Base URL: `https://api.cloudflare.com/client/v4`
162 
163### Authentication
164 
165```bash
166curl -H "Authorization: Bearer $API_TOKEN" https://api.cloudflare.com/client/v4/...
167```
168 
169### Key Endpoints
170 
171| Operation | Method | Endpoint |
172|-----------|--------|----------|
173| Enable routing | POST | `/zones/{zone_id}/email/routing/enable` |
174| Disable routing | POST | `/zones/{zone_id}/email/routing/disable` |
175| List rules | GET | `/zones/{zone_id}/email/routing/rules` |
176| Create rule | POST | `/zones/{zone_id}/email/routing/rules` |
177| Verify destination | POST | `/zones/{zone_id}/email/routing/addresses` |
178| List destinations | GET | `/zones/{zone_id}/email/routing/addresses` |
179 
180### Create Routing Rule Example
181 
182```bash
183curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/email/routing/rules" \
184  -H "Authorization: Bearer $API_TOKEN" \
185  -H "Content-Type: application/json" \
186  -d '{
187    "enabled": true,
188    "name": "Forward sales",
189    "matchers": [{"type": "literal", "field": "to", "value": "[email protected]"}],
190    "actions": [{"type": "forward", "value": ["[email protected]"]}],
191    "priority": 0
192  }'
193```
194 
195Matcher types: `literal` (exact match), `all` (catch-all).
196