1# Email Workers Gotchas
2 
3## Critical Issues
4 
5### ReadableStream Single-Use
6 
7```typescript
8// ❌ WRONG: Stream consumed twice
9const email = await PostalMime.parse(await new Response(message.raw).arrayBuffer());
10const rawText = await new Response(message.raw).text(); // EMPTY!
11 
12// ✅ CORRECT: Buffer first
13const buffer = await new Response(message.raw).arrayBuffer();
14const email = await PostalMime.parse(buffer);
15const rawText = new TextDecoder().decode(buffer);
16```
17 
18### ctx.waitUntil() Errors Silent
19 
20```typescript
21// ❌ Errors dropped silently
22ctx.waitUntil(fetch(webhookUrl, { method: 'POST', body: data }));
23 
24// ✅ Catch and log
25ctx.waitUntil(
26  fetch(webhookUrl, { method: 'POST', body: data })
27    .catch(err => env.ERROR_LOG.put(`error:${Date.now()}`, err.message))
28);
29```
30 
31## Security
32 
33### Envelope vs Header From (Spoofing)
34 
35```typescript
36const envelopeFrom = message.from;               // SMTP MAIL FROM (trusted)
37const headerFrom = (await PostalMime.parse(buffer)).from?.address; // (untrusted)
38// Use envelope for security decisions
39```
40 
41### Input Validation
42 
43```typescript
44if (message.rawSize > 5_000_000) { message.setReject('Too large'); return; }
45if ((message.headers.get('Subject') || '').length > 1000) {
46  message.setReject('Invalid subject'); return;
47}
48```
49 
50### DMARC for Replies
51 
52Replies fail silently without DMARC. Verify: `dig TXT _dmarc.example.com`
53 
54## Parsing
55 
56### Address Parsing
57 
58```typescript
59const email = await PostalMime.parse(buffer);
60const fromAddress = email.from?.address || 'unknown';
61const toAddresses = Array.isArray(email.to) ? email.to.map(t => t.address) : [email.to?.address];
62```
63 
64### Character Encoding
65 
66Let postal-mime handle decoding - `email.subject`, `email.text`, `email.html` are UTF-8.
67 
68## API Behavior
69 
70### setReject() vs throw
71 
72```typescript
73// setReject() for SMTP rejection
74if (blockList.includes(message.from)) { message.setReject('Blocked'); return; }
75 
76// throw for worker errors
77if (!env.KV) throw new Error('KV not configured');
78```
79 
80### forward() Only X-* Headers
81 
82```typescript
83headers.set('X-Processed-By', 'worker');  // ✅ Works
84headers.set('Subject', 'Modified');        // ❌ Dropped
85```
86 
87### Reply Requires Verified Domain
88 
89```typescript
90// Use same domain as receiving address
91const receivingDomain = message.to.split('@')[1];
92await message.reply(new EmailMessage(`noreply@${receivingDomain}`, message.from, rawMime));
93```
94 
95## Performance
96 
97### CPU Limit
98 
99```typescript
100// Skip parsing large emails
101if (message.rawSize > 5_000_000) {
102  await message.forward('[email protected]');
103  return;
104}
105```
106 
107Monitor: `npx wrangler tail`
108 
109## Limits
110 
111| Limit | Value |
112|-------|-------|
113| Max message size | 25 MiB |
114| Max rules/zone | 200 |
115| CPU time (free/paid) | 10ms / 30s default, 5min max |
116| Reply References | 100 |
117 
118## Common Errors
119 
120| Error | Fix |
121|-------|-----|
122| "Address not verified" | Add in Email Routing dashboard |
123| "Exceeded CPU time" | Use `ctx.waitUntil()` or upgrade |
124| "Stream is locked" | Buffer `message.raw` first |
125| Silent reply failure | Check DMARC records |
126