1# Email Workers API Reference
2 
3Complete API reference for Cloudflare Email Workers runtime.
4 
5## ForwardableEmailMessage Interface
6 
7The main interface passed to email handlers.
8 
9```typescript
10interface ForwardableEmailMessage {
11  readonly from: string;        // Envelope MAIL FROM (SMTP sender)
12  readonly to: string;          // Envelope RCPT TO (SMTP recipient)
13  readonly headers: Headers;    // Web-standard Headers object
14  readonly raw: ReadableStream; // Raw MIME message (single-use stream)
15  readonly rawSize: number;     // Total message size in bytes
16  
17  setReject(reason: string): void;
18  forward(rcptTo: string, headers?: Headers): Promise<void>;
19  reply(message: EmailMessage): Promise<void>;
20}
21```
22 
23### Properties
24 
25| Property | Type | Description |
26|----------|------|-------------|
27| `from` | string | Envelope sender (SMTP MAIL FROM) - use for security |
28| `to` | string | Envelope recipient (SMTP RCPT TO) |
29| `headers` | Headers | Message headers (Subject, Message-ID, etc.) |
30| `raw` | ReadableStream | Raw MIME message (**single-use**, buffer first) |
31| `rawSize` | number | Message size in bytes |
32 
33### Methods
34 
35#### setReject(reason: string): void
36 
37Reject with permanent SMTP 5xx error. Email not delivered, sender may receive bounce.
38 
39```typescript
40if (blockList.includes(message.from)) {
41  message.setReject('Sender blocked');
42}
43```
44 
45#### forward(rcptTo: string, headers?: Headers): Promise<void>
46 
47Forward to verified destination. Only `X-*` custom headers allowed.
48 
49```typescript
50await message.forward('[email protected]');
51 
52// With custom headers
53const h = new Headers();
54h.set('X-Processed-By', 'worker');
55await message.forward('[email protected]', h);
56```
57 
58#### reply(message: EmailMessage): Promise<void>
59 
60Send a reply to the original sender (March 2025 feature).
61 
62```typescript
63import { EmailMessage } from 'cloudflare:email';
64import { createMimeMessage } from 'mimetext';
65 
66const msg = createMimeMessage();
67msg.setSender({ name: 'Support', addr: '[email protected]' });
68msg.setRecipient(message.from);
69msg.setSubject(`Re: ${message.headers.get('Subject')}`);
70msg.setHeader('In-Reply-To', message.headers.get('Message-ID'));
71msg.setHeader('References', message.headers.get('References') || '');
72msg.addMessage({
73  contentType: 'text/plain',
74  data: 'Thank you for your message.'
75});
76 
77await message.reply(new EmailMessage(
78  '[email protected]',
79  message.from,
80  msg.asRaw()
81));
82```
83 
84**Requirements**:
85- Incoming email needs valid DMARC
86- Reply once per event, recipient = `message.from`
87- Sender domain = receiving domain, with DMARC/SPF/DKIM
88- Max 100 `References` entries
89- Threading: `In-Reply-To` (original Message-ID), `References`, new `Message-ID`
90 
91## EmailMessage Constructor
92 
93```typescript
94import { EmailMessage } from 'cloudflare:email';
95 
96new EmailMessage(from: string, to: string, raw: ReadableStream | string)
97```
98 
99Used for sending emails (replies or via SendEmail binding). Domain must be verified.
100 
101## SendEmail Interface
102 
103```typescript
104interface SendEmail {
105  send(message: EmailMessage): Promise<void>;
106}
107 
108// Usage
109await env.EMAIL.send(new EmailMessage(from, to, mimeContent));
110```
111 
112## SendEmail Binding Types
113 
114```jsonc
115{
116  "send_email": [
117    { "name": "EMAIL" },  // Type 1: Any verified address
118    { "name": "LOGS", "destination_address": "[email protected]" },  // Type 2: Single dest
119    { "name": "TEAM", "allowed_destination_addresses": ["[email protected]", "[email protected]"] },  // Type 3: Dest allowlist
120    { "name": "NOREPLY", "allowed_sender_addresses": ["[email protected]"] }  // Type 4: Sender allowlist
121  ]
122}
123```
124 
125## postal-mime Parsed Output
126 
127postal-mime v2.7.3 parses incoming emails into structured data.
128 
129```typescript
130interface ParsedEmail {
131  headers: Array<{ key: string; value: string }>;
132  from: { name: string; address: string } | null;
133  to: Array<{ name: string; address: string }> | { name: string; address: string } | null;
134  cc: Array<{ name: string; address: string }> | null;
135  bcc: Array<{ name: string; address: string }> | null;
136  subject: string;
137  messageId: string | null;
138  inReplyTo: string | null;
139  references: string | null;
140  date: string | null;
141  html: string | null;
142  text: string | null;
143  attachments: Array<{
144    filename: string;
145    mimeType: string;
146    disposition: string | null;
147    related: boolean;
148    contentId: string | null;
149    content: Uint8Array;
150  }>;
151}
152```
153 
154### Usage
155 
156```typescript
157import PostalMime from 'postal-mime';
158 
159const buffer = await new Response(message.raw).arrayBuffer();
160const email = await PostalMime.parse(buffer);
161 
162console.log(email.subject);
163console.log(email.from?.address);
164console.log(email.text);
165console.log(email.attachments.length);
166```
167 
168## mimetext API Quick Reference
169 
170mimetext v3.0.27 composes outgoing emails.
171 
172```typescript
173import { createMimeMessage } from 'mimetext';
174 
175const msg = createMimeMessage();
176 
177// Sender
178msg.setSender({ name: 'John Doe', addr: '[email protected]' });
179 
180// Recipients
181msg.setRecipient('[email protected]');
182msg.setRecipients(['[email protected]', '[email protected]']);
183msg.setCc('[email protected]');
184msg.setBcc(['[email protected]']);
185 
186// Headers
187msg.setSubject('Meeting Notes');
188msg.setHeader('In-Reply-To', '<previous-message-id>');
189msg.setHeader('References', '<msg1> <msg2>');
190msg.setHeader('Message-ID', `<${crypto.randomUUID()}@example.com>`);
191 
192// Content
193msg.addMessage({
194  contentType: 'text/plain',
195  data: 'Plain text content'
196});
197 
198msg.addMessage({
199  contentType: 'text/html',
200  data: '<p>HTML content</p>'
201});
202 
203// Attachments
204msg.addAttachment({
205  filename: 'report.pdf',
206  contentType: 'application/pdf',
207  data: pdfBuffer // Uint8Array or base64 string
208});
209 
210// Generate raw MIME
211const raw = msg.asRaw(); // Returns string
212```
213 
214## TypeScript Types
215 
216```typescript
217import { 
218  ForwardableEmailMessage,
219  EmailMessage 
220} from 'cloudflare:email';
221 
222interface Env {
223  EMAIL: SendEmail;
224  EMAIL_ARCHIVE: KVNamespace;
225  ALLOWED_SENDERS: KVNamespace;
226}
227 
228export default {
229  async email(
230    message: ForwardableEmailMessage,
231    env: Env,
232    ctx: ExecutionContext
233  ): Promise<void> {
234    // Fully typed
235  }
236};
237```
238