REST API 允许你通过向 POST /accounts/{account_id}/email/sending/send 发送标准 HTTP 请求，从任意应用发送邮件。可用于任意后端、serverless 函数或 CI/CD 流水线——无需 Cloudflare Workers 绑定。
完整 OpenAPI 规范请参阅 Email Sending API 参考。
Cloudflare 还为 REST API 提供官方 SDK：Node、Python 和 Go。
使用具有发送邮件权限的 Cloudflare API token 进行身份验证。将其包含在 Authorization 标头中：
Authorization: Bearer <API_TOKEN>curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"to": "[email protected]",
"from": "[email protected]",
"subject": "Welcome to our service!",
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
"text": "Welcome! Thanks for signing up."
}'有关多个收件人、CC/BCC 以及带名称的地址，请参阅指定收件人。
通过在 attachments 数组中包含 base64 编码的内容来发送文件。整封邮件大小（含附件）不得超过 5 MiB。
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"to": "[email protected]",
"from": "[email protected]",
"subject": "Your Invoice",
"html": "<h1>Invoice attached</h1><p>Please find your invoice attached.</p>",
"attachments": [
{
"content": "JVBERi0xLjQKJeLjz9MK...",
"filename": "invoice-12345.pdf",
"type": "application/pdf",
"disposition": "attachment"
}
]
}'有关内联图片和文件上传，请参阅邮件附件。
为会话线程、列表管理或跟踪设置自定义标头。允许的标头完整列表请参阅电子邮件标头参考。
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"to": "[email protected]",
"from": "[email protected]",
"subject": "Your weekly digest",
"html": "<h1>Weekly Digest</h1>",
"headers": {
"List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=abc123>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
"X-Campaign-ID": "weekly-digest-2026-03"
}
}'成功响应会返回每个收件人的投递状态：
{
"success": true,
"errors": [],
"messages": [],
"result": {
"delivered": ["[email protected]"],
"permanent_bounces": [],
"queued": []
}
}delivered— 消息已立即投递到的电子邮件地址permanent_bounces— 发生永久退信的电子邮件地址queued— 投递已排队稍后处理的电子邮件地址
REST API 返回标准的 Cloudflare API 错误响应。失败请求会返回包含数字错误代码和机器可读消息的 errors 数组：
{
"success": false,
"errors": [
{
"code": 10001,
"message": "email.sending.error.invalid_request_schema"
}
],
"messages": [],
"result": null
}REST API 错误代码：
| HTTP 状态 | 代码 | 消息 | 说明 |
|---|---|---|---|
| 400 | 10001 | email.sending.error.invalid_request_schema |
请求格式无效 |
| 400 | 10200 | email.sending.error.email.too_big |
邮件超出大小限制 |
| 400 | 10201 | email.sending.error.email.no_content_length |
缺少 content length |
| 400 | 10202 | email.sending.error.email.invalid |
邮件内容无效 |
| 401 | 10101 | email.sending.error.authentication.unauthorized |
缺少或无效的 API token |
| 401 | 10103 | email.sending.error.authentication.bad_token_type |
此端点的 token 类型不正确 |
| 403 | 10102 | email.sending.error.authentication.forbidden |
token 缺少发送权限 |
| 403 | 10105 | email.sending.error.authentication.not_entitled |
账户无权使用 Email Sending |
| 403 | 10203 | email.sending.error.email.sending_disabled |
此 zone 或账户已禁用发送 |
| 404 | 10000 | email.sending.error.not_found |
未找到资源 |
| 429 | 10004 | email.sending.error.throttled |
超出速率限制 |
| 500 | 10002 | email.sending.error.internal_server |
内部服务器错误 |
| 500 | 10003 | email.sending.error.not_implemented |
操作未实现 |
| 503 | 10100 | email.sending.error.authentication.upstream |
身份验证服务暂时不可用 |
- 完整请求与响应 schema 请参阅 Email Sending API 参考。
- 从 Cloudflare Workers 使用绑定直接发送邮件，请参阅 Workers API。
- 从任意支持 SMTP 的应用或邮件客户端发送，请参阅 SMTP。
- 查看电子邮件标头，了解会话线程、列表管理和自定义跟踪标头。