Skip to content

Commit b7c56c7

Browse files
thomasgauvinthomasgauvin
committed
fix: audit and correct email service docs for accuracy across 20 files
Cross-referenced docs against fwdr source code, workerd C++ bindings, published API spec, and internal discussions to fix: - API endpoint path: /email-service/send -> /email/sending/send - REST API field names: from.email -> from.address, replyTo -> reply_to - REST API response shape: messageId -> delivered/permanent_bounces/queued - Interface type: EmailBinding -> SendEmail (matches workerd) - Remove sendBatch() (not implemented) - Fix EmailSendResult (no success field, not a class) - Error codes: remove 4 non-existent, add E_RECIPIENT_NOT_ALLOWED - SPF record: _spf.cloudflare.com -> _spf.email.cloudflare.net - Recipients limit: 100 -> 50 (matches MAX_RCPTS) - Remove fictitious hourly/monthly quota columns - Remove default daily limit numbers - DKIM record type: CNAME -> TXT - Add canBeForwarded to ForwardableEmailMessage - Fix legacy /email-routing/ links - Remove sandbox/production access terminology - Add pricing: $0.35 per 1,000 emails - Free plan: can send to account-owned verified addresses - Fix replyAt typo in deliverability docs
1 parent 8280431 commit b7c56c7

20 files changed

Lines changed: 100 additions & 265 deletions

File tree

‎src/content/docs/email-service/api/route-emails/email-handler.mdx‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Add the `email` handler function to your Worker's exported handlers:
1717

1818
```typescript
1919
interface Env {
20-
EMAIL: EmailBinding;
20+
EMAIL: SendEmail;
2121
}
2222

2323
export default {
@@ -42,11 +42,12 @@ The `message` parameter provides access to the incoming email:
4242

4343
```typescript
4444
interface ForwardableEmailMessage {
45-
readonly from: string; // Sender email address
46-
readonly to: string; // Recipient email address
47-
readonly headers: Headers; // Email headers
48-
readonly raw: ReadableStream; // Raw email content stream
45+
readonly from: string; // Sender email address (envelope MAIL FROM)
46+
readonly to: string; // Recipient email address (envelope RCPT TO)
47+
readonly headers: Headers; // Email headers (Subject, Message-ID, etc.)
48+
readonly raw: ReadableStream; // Raw MIME email content stream
4949
readonly rawSize: number; // Size of raw email in bytes
50+
readonly canBeForwarded: boolean; // Whether the message can be forwarded
5051

5152
// Actions
5253
setReject(reason: string): void;
@@ -263,7 +264,7 @@ Send automatic replies using the Email Service binding:
263264

264265
```typescript
265266
interface Env {
266-
EMAIL: EmailBinding;
267+
EMAIL: SendEmail;
267268
}
268269

269270
export default {

‎src/content/docs/email-service/api/send-emails/rest-api.mdx‎

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ For the full OpenAPI specification, refer to the [Email Sending API reference](h
1414
## Endpoint
1515

1616
```txt
17-
POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send
17+
POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send
1818
```
1919

2020
## Authentication
@@ -31,7 +31,7 @@ Authorization: Bearer <API_TOKEN>
3131
<TabItem label="Simple email">
3232

3333
```bash
34-
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
34+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
3535
--header "Authorization: Bearer <API_TOKEN>" \
3636
--header "Content-Type: application/json" \
3737
--data '{
@@ -47,12 +47,12 @@ curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/s
4747
<TabItem label="Multiple recipients">
4848

4949
```bash
50-
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
50+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
5151
--header "Authorization: Bearer <API_TOKEN>" \
5252
--header "Content-Type: application/json" \
5353
--data '{
5454
"to": ["user1@example.com", "user2@example.com"],
55-
"from": { "email": "newsletter@yourdomain.com", "name": "Newsletter Team" },
55+
"from": { "address": "newsletter@yourdomain.com", "name": "Newsletter Team" },
5656
"subject": "Monthly Newsletter",
5757
"html": "<h1>This month'\''s updates</h1>",
5858
"text": "This month'\''s updates"
@@ -63,15 +63,15 @@ curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/s
6363
<TabItem label="With CC and BCC">
6464

6565
```bash
66-
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
66+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
6767
--header "Authorization: Bearer <API_TOKEN>" \
6868
--header "Content-Type: application/json" \
6969
--data '{
7070
"to": "customer@example.com",
7171
"cc": ["manager@company.com"],
7272
"bcc": ["archive@company.com"],
7373
"from": "orders@yourdomain.com",
74-
"replyTo": "support@yourdomain.com",
74+
"reply_to": "support@yourdomain.com",
7575
"subject": "Order Confirmation #12345",
7676
"html": "<h1>Your order is confirmed</h1>",
7777
"text": "Your order is confirmed"
@@ -86,7 +86,7 @@ curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/s
8686
Send files by including base64-encoded content in the `attachments` array:
8787

8888
```bash
89-
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
89+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
9090
--header "Authorization: Bearer <API_TOKEN>" \
9191
--header "Content-Type: application/json" \
9292
--data '{
@@ -110,7 +110,7 @@ curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/s
110110
Set custom headers for threading, list management, or tracking. Refer to the [email headers reference](/email-service/reference/headers/) for the full list of allowed headers.
111111

112112
```bash
113-
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
113+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
114114
--header "Authorization: Bearer <API_TOKEN>" \
115115
--header "Content-Type: application/json" \
116116
--data '{
@@ -126,23 +126,48 @@ curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/s
126126
}'
127127
```
128128

129+
## Response
130+
131+
A successful response returns the delivery status for each recipient:
132+
133+
```json
134+
{
135+
"success": true,
136+
"errors": [],
137+
"messages": [],
138+
"result": {
139+
"delivered": ["recipient@example.com"],
140+
"permanent_bounces": [],
141+
"queued": []
142+
}
143+
}
144+
```
145+
146+
- `delivered` - Email addresses to which the message was delivered immediately.
147+
- `permanent_bounces` - Email addresses that permanently bounced.
148+
- `queued` - Email addresses for which delivery was queued for later.
149+
129150
## Error handling
130151

131-
The REST API returns standard Cloudflare API responses. A failed request returns an `errors` array:
152+
The REST API returns standard Cloudflare API error responses. A failed request returns an `errors` array with numeric error codes:
132153

133154
```json
134155
{
135156
"success": false,
136157
"errors": [
137158
{
138-
"code": "E_SENDER_NOT_VERIFIED",
159+
"code": 1000,
139160
"message": "Sender domain not verified"
140161
}
141-
]
162+
],
163+
"messages": [],
164+
"result": null
142165
}
143166
```
144167

145-
Refer to the [error codes table](/email-service/api/send-emails/workers-api/#error-codes) for the full list of error codes and their causes.
168+
:::note[Workers binding vs REST API errors]
169+
The REST API returns standard Cloudflare API numeric error codes, while the [Workers binding](/email-service/api/send-emails/workers-api/) throws errors with string codes (for example, `E_SENDER_NOT_VERIFIED`). Refer to the [Workers API error codes table](/email-service/api/send-emails/workers-api/#error-codes) for the string error codes.
170+
:::
146171

147172
## Next steps
148173

0 commit comments

Comments
 (0)