Skip to content

Commit f78d228

Browse files
thomasgauvinthomasgauvin
committed
docs: thoroughly surface REST API across email service docs
- Flesh out rest-api.mdx with tabs (simple, multiple recipients, CC/BCC), attachments, custom headers, and error handling sections - Add REST API curl tab as the first tab on the index.mdx landing page - Add 'Send your first email with the REST API' section to get-started - Add REST API curl tab to headers.mdx usage examples - Update workers-api.mdx intro to cross-link REST API as alternative - Update limits.mdx to clarify which limits apply to both APIs vs Workers only - Add REST API note to local-development/sending.mdx - Add REST API context note to examples/email-sending index - Fix stale react: field in workers-api.mdx batch template example - Fix 3 broken links to /email-service/configuration/workers/
1 parent 63b1edd commit f78d228

10 files changed

Lines changed: 220 additions & 35 deletions

File tree

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

Lines changed: 118 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,40 +5,147 @@ sidebar:
55
order: 2
66
---
77

8-
The REST API allows you to send emails from any application using standard HTTP requests. This is useful for applications that are not built on Cloudflare Workers or when you need to send emails from external services.
8+
import { Tabs, TabItem } from "~/components";
99

10-
## Endpoint
10+
The REST API allows you to send emails from any application using standard HTTP requests. Use it from any backend, serverless function, or CI/CD pipeline — no Cloudflare Workers binding required.
11+
12+
For the full OpenAPI specification, refer to the [Email Sending API reference](https://developers.cloudflare.com/api/resources/email_sending/methods/send).
1113

12-
Send an email using the [Email Sending REST API](https://developers.cloudflare.com/api/resources/email_sending/methods/send).
14+
## Endpoint
1315

1416
```txt
1517
POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send
1618
```
1719

1820
## Authentication
1921

20-
Authenticate using a Cloudflare API token with the appropriate permissions. Include the token in the `Authorization` header:
22+
Authenticate with a [Cloudflare API token](/fundamentals/api/get-started/create-token/) that has permission to send emails. Include it in the `Authorization` header:
2123

2224
```txt
2325
Authorization: Bearer <API_TOKEN>
2426
```
2527

26-
## Example
28+
## Send an email
29+
30+
<Tabs>
31+
<TabItem label="Simple email">
2732

2833
```bash
2934
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
3035
--header "Authorization: Bearer <API_TOKEN>" \
3136
--header "Content-Type: application/json" \
3237
--data '{
3338
"to": "recipient@example.com",
34-
"from": "sender@yourdomain.com",
35-
"subject": "Hello from Email Service",
36-
"html": "<h1>Hello!</h1><p>This email was sent using the REST API.</p>",
37-
"text": "Hello! This email was sent using the REST API."
39+
"from": "welcome@yourdomain.com",
40+
"subject": "Welcome to our service!",
41+
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
42+
"text": "Welcome! Thanks for signing up."
43+
}'
44+
```
45+
46+
</TabItem>
47+
<TabItem label="Multiple recipients">
48+
49+
```bash
50+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
51+
--header "Authorization: Bearer <API_TOKEN>" \
52+
--header "Content-Type: application/json" \
53+
--data '{
54+
"to": ["user1@example.com", "user2@example.com"],
55+
"from": { "email": "newsletter@yourdomain.com", "name": "Newsletter Team" },
56+
"subject": "Monthly Newsletter",
57+
"html": "<h1>This month'\''s updates</h1>",
58+
"text": "This month'\''s updates"
59+
}'
60+
```
61+
62+
</TabItem>
63+
<TabItem label="With CC and BCC">
64+
65+
```bash
66+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
67+
--header "Authorization: Bearer <API_TOKEN>" \
68+
--header "Content-Type: application/json" \
69+
--data '{
70+
"to": "customer@example.com",
71+
"cc": ["manager@company.com"],
72+
"bcc": ["archive@company.com"],
73+
"from": "orders@yourdomain.com",
74+
"replyTo": "support@yourdomain.com",
75+
"subject": "Order Confirmation #12345",
76+
"html": "<h1>Your order is confirmed</h1>",
77+
"text": "Your order is confirmed"
78+
}'
79+
```
80+
81+
</TabItem>
82+
</Tabs>
83+
84+
## Attachments
85+
86+
Send files by including base64-encoded content in the `attachments` array:
87+
88+
```bash
89+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
90+
--header "Authorization: Bearer <API_TOKEN>" \
91+
--header "Content-Type: application/json" \
92+
--data '{
93+
"to": "customer@example.com",
94+
"from": "invoices@yourdomain.com",
95+
"subject": "Your Invoice",
96+
"html": "<h1>Invoice attached</h1><p>Please find your invoice attached.</p>",
97+
"attachments": [
98+
{
99+
"content": "JVBERi0xLjQKJeLjz9MK...",
100+
"filename": "invoice-12345.pdf",
101+
"type": "application/pdf",
102+
"disposition": "attachment"
103+
}
104+
]
105+
}'
106+
```
107+
108+
## Custom headers
109+
110+
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.
111+
112+
```bash
113+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
114+
--header "Authorization: Bearer <API_TOKEN>" \
115+
--header "Content-Type: application/json" \
116+
--data '{
117+
"to": "user@example.com",
118+
"from": "notifications@yourdomain.com",
119+
"subject": "Your weekly digest",
120+
"html": "<h1>Weekly Digest</h1>",
121+
"headers": {
122+
"List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=abc123>",
123+
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
124+
"X-Campaign-ID": "weekly-digest-2026-03"
125+
}
38126
}'
39127
```
40128

129+
## Error handling
130+
131+
The REST API returns standard Cloudflare API responses. A failed request returns an `errors` array:
132+
133+
```json
134+
{
135+
"success": false,
136+
"errors": [
137+
{
138+
"code": "E_SENDER_NOT_VERIFIED",
139+
"message": "Sender domain not verified"
140+
}
141+
]
142+
}
143+
```
144+
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.
146+
41147
## Next steps
42148

43-
- Refer to the [REST API reference](https://developers.cloudflare.com/api/resources/email_sending/methods/send) for full request and response schemas.
44-
- See the [Workers API](/email-service/api/send-emails/workers-api/) for sending emails directly from Cloudflare Workers.
149+
- Refer to the [Email Sending API reference](https://developers.cloudflare.com/api/resources/email_sending/methods/send) for the full request and response schemas.
150+
- See the [Workers API](/email-service/api/send-emails/workers-api/) for sending emails directly from Cloudflare Workers using bindings.
151+
- Review [email headers](/email-service/reference/headers/) for threading, list management, and custom tracking headers.

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

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ sidebar:
77

88
import { Tabs, TabItem, WranglerConfig } from "~/components";
99

10-
The Workers API provides native email sending capabilities directly from your Cloudflare Workers. This is the recommended method for applications built on the Cloudflare platform.
10+
The Workers API provides native email sending capabilities directly from your Cloudflare Workers through bindings. If you are not using Workers, you can send emails using the [REST API](/email-service/api/send-emails/rest-api/) instead.
1111

1212
## Email binding
1313

@@ -243,10 +243,8 @@ const emails = subscribers.map(subscriber => ({
243243
to: subscriber.email,
244244
from: "updates@yourdomain.com",
245245
subject: `Your ${subscriber.plan} plan update`,
246-
react: <PlanUpdateEmail
247-
name={subscriber.name}
248-
plan={subscriber.plan}
249-
/>
246+
html: `<h1>Hi ${subscriber.name}!</h1><p>Here's your ${subscriber.plan} plan update.</p>`,
247+
text: `Hi ${subscriber.name}! Here's your ${subscriber.plan} plan update.`,
250248
}));
251249

252250
const batchResponse = await env.EMAIL.sendBatch(emails);
@@ -453,6 +451,7 @@ export default {
453451

454452
**Next steps:**
455453

456-
- See [practical examples](/email-service/examples/) of Workers API usage
454+
- See the [REST API](/email-service/api/send-emails/rest-api/) for sending emails without Workers
455+
- See [practical examples](/email-service/examples/) of email sending patterns
457456
- Learn about [email routing](/email-service/api/route-emails/) for handling incoming emails
458457
- Explore [email authentication](/email-service/concepts/email-authentication/) for better deliverability

‎src/content/docs/email-service/configuration/domains.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -428,7 +428,7 @@ Proper domain configuration is essential for Email Service functionality:
428428

429429
## Next steps
430430

431-
- **[Workers configuration](/email-service/configuration/workers/)**: Set up email bindings
431+
- **[Send emails API](/email-service/api/send-emails/)**: Workers binding and REST API reference
432432
- **[Domain authentication (DKIM and SPF)](/email-service/concepts/email-authentication/)**: Learn about SPF, DKIM, and DMARC
433433
- **[Deliverability](/email-service/concepts/deliverability/)**: Optimize email delivery
434434

‎src/content/docs/email-service/examples/email-sending/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,6 @@ sidebar:
99

1010
import { DirectoryListing } from "~/components";
1111

12-
Advanced patterns and examples for sending emails with Cloudflare Email Service.
12+
Advanced patterns and examples for sending emails with Cloudflare Email Service. These examples use the [Workers binding](/email-service/api/send-emails/workers-api/). If you are using the [REST API](/email-service/api/send-emails/rest-api/), the same `EmailMessage` fields (`to`, `from`, `subject`, `html`, `attachments`, `headers`) apply — send them as JSON in your HTTP request body.
1313

1414
<DirectoryListing />

‎src/content/docs/email-service/get-started/send-emails.mdx‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Send emails
33
pcx_content_type: get-started
44
summary: |
5-
Send your first email using Cloudflare Email Service with Workers API.
5+
Send your first email using the REST API or Workers binding.
66
sidebar:
77
order: 1
88
---
@@ -17,19 +17,47 @@ import {
1717
} from "~/components";
1818
import DomainSetup from "~/content/partials/email-service/_domain-setup-sending.mdx";
1919

20-
Send emails from your applications using Cloudflare Email Service with the Workers API or the [REST API](https://developers.cloudflare.com/api/resources/email_sending/methods/send).
20+
Send emails from your applications using Cloudflare Email Service. You can use the **REST API** from any platform or the **Workers binding** for applications built on Cloudflare Workers.
2121

2222
:::note
2323
You must be using Cloudflare DNS to use Email Service.
2424
:::
2525

2626
<DomainSetup />
2727

28-
## Send your first email
28+
## Send your first email with the REST API
2929

30-
Send your first email from Workers using the Workers API.
30+
Send an email with a single `curl` command. Replace `{account_id}` with your [Cloudflare account ID](/fundamentals/setup/find-account-and-zone-ids/) and `<API_TOKEN>` with an [API token](/fundamentals/api/get-started/create-token/).
3131

32-
Start by creating a new Worker project.
32+
```bash
33+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
34+
--header "Authorization: Bearer <API_TOKEN>" \
35+
--header "Content-Type: application/json" \
36+
--data '{
37+
"to": "recipient@example.com",
38+
"from": "welcome@yourdomain.com",
39+
"subject": "Welcome to our service!",
40+
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
41+
"text": "Welcome! Thanks for signing up."
42+
}'
43+
```
44+
45+
A successful response includes a `messageId`:
46+
47+
```json
48+
{
49+
"success": true,
50+
"result": {
51+
"messageId": "<unique-message-id>"
52+
}
53+
}
54+
```
55+
56+
For more details, see the [REST API reference](/email-service/api/send-emails/rest-api/).
57+
58+
## Send your first email with Workers
59+
60+
If you are building on Cloudflare Workers, you can use the Workers binding for native email sending. Start by creating a new Worker project.
3361

3462
1. Create a new Worker project:
3563

‎src/content/docs/email-service/index.mdx‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -50,10 +50,26 @@ Together, these two features make it possible for you to send and receive emails
5050
- Custom email addresses (support@, contact@, orders@)
5151
- Emails as a mode of interaction for agents, such as send an email to create an issue in ticket tracking
5252

53-
Access Email Service from Cloudflare Workers using Workers Bindings or via the [REST API](https://developers.cloudflare.com/api/resources/email_sending/methods/send):
53+
Access Email Service using the [REST API](/email-service/api/send-emails/rest-api/) from any platform, or directly from Cloudflare Workers using [bindings](/email-service/api/send-emails/workers-api/):
5454

5555
<Tabs>
56-
<TabItem label="index.ts">
56+
<TabItem label="REST API (curl)">
57+
58+
```bash
59+
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email-service/send" \
60+
--header "Authorization: Bearer <API_TOKEN>" \
61+
--header "Content-Type: application/json" \
62+
--data '{
63+
"to": "user@example.com",
64+
"from": "welcome@yourdomain.com",
65+
"subject": "Welcome to our service!",
66+
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
67+
"text": "Welcome! Thanks for signing up."
68+
}'
69+
```
70+
71+
</TabItem>
72+
<TabItem label="index.ts (Workers)">
5773
```ts
5874
export default {
5975
// Handle HTTP requests (Email Sending)
@@ -117,7 +133,7 @@ export default {
117133
</TabItem>
118134
</Tabs>
119135
120-
See the full [Workers Email API reference](/email-service/api/send-emails/workers-api/).
136+
See the full [API reference](/email-service/api/send-emails/) for the REST API and Workers binding.
121137
122138
<LinkButton href="/email-service/get-started/">Get started</LinkButton>
123139
@@ -144,8 +160,8 @@ See the full [Workers Email API reference](/email-service/api/send-emails/worker
144160
Monitor email performance with comprehensive metrics and alerting.
145161
</Feature>
146162
147-
<Feature header="Workers API" href="/email-service/api/">
148-
Send and route emails using the native Workers API or the [REST API](https://developers.cloudflare.com/api/resources/email_sending/methods/send).
163+
<Feature header="API" href="/email-service/api/">
164+
Send and route emails using the [REST API](/email-service/api/send-emails/rest-api/) or [Workers binding](/email-service/api/send-emails/workers-api/).
149165
</Feature>
150166
151167
---

‎src/content/docs/email-service/local-development/routing.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,5 +124,5 @@ This will output the parsed email structure in the console:
124124

125125
## Next steps
126126

127-
- Deploy your routing worker: [Email Routing configuration](/email-service/configuration/workers/)
127+
- Deploy your routing worker: [Route emails get started](/email-service/get-started/route-emails/)
128128
- See advanced patterns: [Email routing examples](/email-service/examples/email-routing/)

‎src/content/docs/email-service/local-development/sending.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ import { WranglerConfig } from "~/components";
1010

1111
Test email sending functionality locally using `wrangler dev` to simulate email delivery and verify your sending logic before deploying.
1212

13+
:::note
14+
If you are using the [REST API](/email-service/api/send-emails/rest-api/) instead of Workers, you can test by sending requests directly with `curl` or any HTTP client — no local development server is required. The rest of this page covers the Workers local development flow.
15+
:::
16+
1317
## Prerequisites
1418

1519
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed
@@ -137,5 +141,5 @@ You can:
137141

138142
## Next steps
139143

140-
- Deploy your sending worker: [Email Service configuration](/email-service/configuration/workers/)
144+
- Deploy your sending worker: [Send emails get started](/email-service/get-started/send-emails/)
141145
- See advanced patterns: [Email sending examples](/email-service/examples/email-sending/)

‎src/content/docs/email-service/platform/limits.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ sidebar:
55
order: 1
66
---
77

8-
Cloudflare Email Service has the following limits to ensure optimal performance and prevent abuse.
8+
Cloudflare Email Service has the following limits to ensure optimal performance and prevent abuse. These limits apply to emails sent via both the [REST API](/email-service/api/send-emails/rest-api/) and the [Workers binding](/email-service/api/send-emails/workers-api/) unless noted otherwise.
99

1010
## Email sending limits
1111

@@ -28,9 +28,9 @@ Cloudflare Email Service has the following limits to ensure optimal performance
2828
| **Attachments** | 10 files, 25MB total | Per email |
2929
| **Header size** | 64KB | All custom headers combined |
3030

31-
## Workers API limits
31+
## Workers binding limits
3232

33-
Email Service integrates with Workers and follows standard Workers limits:
33+
The following limits apply only when sending emails via the [Workers binding](/email-service/api/send-emails/workers-api/). They do not apply to the REST API.
3434

3535
| Limit | Value | Notes |
3636
| --------------- | ---------------- | ------------------------------ |

0 commit comments

Comments
 (0)