1# Common Patterns
2 
3## 1. Allowlist/Blocklist
4 
5```typescript
6// Allowlist
7const allowed = ["[email protected]", "[email protected]"];
8if (!allowed.includes(message.from)) {
9  message.setReject("Not allowed");
10  return;
11}
12await message.forward("[email protected]");
13```
14 
15## 2. Parse Email Body
16 
17```typescript
18import PostalMime from 'postal-mime';
19 
20export default {
21  async email(message, env, ctx) {
22    // CRITICAL: Consume stream immediately
23    const raw = await message.raw.arrayBuffer();
24    
25    const parser = new PostalMime();
26    const email = await parser.parse(raw);
27    
28    console.log({
29      subject: email.subject,
30      text: email.text,
31      html: email.html,
32      from: email.from.address,
33      attachments: email.attachments.length
34    });
35    
36    await message.forward("[email protected]");
37  }
38} satisfies ExportedHandler;
39```
40 
41## 3. Spam Filter
42 
43```typescript
44const score = parseFloat(message.headers.get("x-cf-spamh-score") || "0");
45if (score > 5) {
46  message.setReject("Spam detected");
47  return;
48}
49await message.forward("[email protected]");
50```
51 
52## 4. Archive to R2
53 
54```typescript
55interface Env { R2: R2Bucket; }
56 
57export default {
58  async email(message, env, ctx) {
59    const raw = await message.raw.arrayBuffer();
60    
61    const key = `${new Date().toISOString()}-${message.from}.eml`;
62    await env.R2.put(key, raw, { 
63      httpMetadata: { contentType: "message/rfc822" }
64    });
65    
66    await message.forward("[email protected]");
67  }
68} satisfies ExportedHandler<Env>;
69```
70 
71## 5. Store Metadata in KV
72 
73```typescript
74import PostalMime from 'postal-mime';
75 
76interface Env { KV: KVNamespace; }
77 
78export default {
79  async email(message, env, ctx) {
80    const raw = await message.raw.arrayBuffer();
81    const parser = new PostalMime();
82    const email = await parser.parse(raw);
83    
84    const metadata = {
85      from: email.from.address,
86      subject: email.subject,
87      timestamp: new Date().toISOString(),
88      size: raw.byteLength
89    };
90    
91    await env.KV.put(`email:${Date.now()}`, JSON.stringify(metadata));
92    await message.forward("[email protected]");
93  }
94} satisfies ExportedHandler<Env>;
95```
96 
97## 6. Subject-Based Routing
98 
99```typescript
100export default {
101  async email(message, env, ctx) {
102    const subject = message.headers.get("subject")?.toLowerCase() || "";
103    
104    if (subject.includes("[urgent]")) {
105      await message.forward("[email protected]");
106    } else if (subject.includes("[billing]")) {
107      await message.forward("[email protected]");
108    } else if (subject.includes("[support]")) {
109      await message.forward("[email protected]");
110    } else {
111      await message.forward("[email protected]");
112    }
113  }
114} satisfies ExportedHandler;
115```
116 
117## 7. Auto-Reply
118 
119```typescript
120interface Env {
121  EMAIL: SendEmail;
122  REPLIED: KVNamespace;
123}
124 
125export default {
126  async email(message, env, ctx) {
127    const msgId = message.headers.get("message-id");
128    
129    if (msgId && await env.REPLIED.get(msgId)) {
130      await message.forward("[email protected]");
131      return;
132    }
133    
134    ctx.waitUntil((async () => {
135      await env.EMAIL.send({
136        from: "[email protected]",
137        to: message.from,
138        subject: "Re: " + (message.headers.get("subject") || ""),
139        text: "Thank you. We'll respond within 24h."
140      });
141      if (msgId) await env.REPLIED.put(msgId, "1", { expirationTtl: 604800 });
142    })());
143    
144    await message.forward("[email protected]");
145  }
146} satisfies ExportedHandler<Env>;
147```
148 
149## 8. Extract Attachments
150 
151```typescript
152import PostalMime from 'postal-mime';
153 
154interface Env { ATTACHMENTS: R2Bucket; }
155 
156export default {
157  async email(message, env, ctx) {
158    const parser = new PostalMime();
159    const email = await parser.parse(await message.raw.arrayBuffer());
160    
161    for (const att of email.attachments) {
162      const key = `${Date.now()}-${att.filename}`;
163      await env.ATTACHMENTS.put(key, att.content, {
164        httpMetadata: { contentType: att.mimeType }
165      });
166    }
167    
168    await message.forward("[email protected]");
169  }
170} satisfies ExportedHandler<Env>;
171```
172 
173## 9. Log to D1
174 
175```typescript
176import PostalMime from 'postal-mime';
177 
178interface Env { DB: D1Database; }
179 
180export default {
181  async email(message, env, ctx) {
182    const parser = new PostalMime();
183    const email = await parser.parse(await message.raw.arrayBuffer());
184    
185    ctx.waitUntil(
186      env.DB.prepare("INSERT INTO log (ts, from_addr, subj) VALUES (?, ?, ?)")
187        .bind(new Date().toISOString(), email.from.address, email.subject || "")
188        .run()
189    );
190    
191    await message.forward("[email protected]");
192  }
193} satisfies ExportedHandler<Env>;
194```
195 
196## 10. Multi-Tenant
197 
198```typescript
199interface Env { TENANTS: KVNamespace; }
200 
201export default {
202  async email(message, env, ctx) {
203    const subdomain = message.to.split("@")[1].split(".")[0];
204    const config = await env.TENANTS.get(subdomain, "json") as { forward: string } | null;
205    
206    if (!config) {
207      message.setReject("Unknown tenant");
208      return;
209    }
210    
211    await message.forward(config.forward);
212  }
213} satisfies ExportedHandler<Env>;
214```
215 
216## Summary
217 
218| Pattern | Use Case | Storage |
219|---------|----------|---------|
220| Allowlist | Security | None |
221| Parse | Body/attachments | None |
222| Spam Filter | Reduce spam | None |
223| R2 Archive | Email storage | R2 |
224| KV Meta | Analytics | KV |
225| Subject Route | Dept routing | None |
226| Auto-Reply | Support | KV |
227| Attachments | Doc mgmt | R2 |
228| D1 Log | Audit trail | D1 |
229| Multi-Tenant | SaaS | KV |
230