在使用 Cloudflare Email Service 发送电子邮件时，您可以使用 Workers API 或 REST API 中的 headers 字段来设置自定义标头。Email Service 使用基于允许列表的方法 —— 仅接受明确批准的标头。任何不在允许列表上的标头（并且不是以 X- 为前缀的自定义标头）都将在 API 级别被拒绝并返回明确的错误。
当通过 SMTP 发送时，请直接在 MIME 消息中设置标头，而不是通过 headers 字段。同样适用此允许列表。
这些标头是由 Cloudflare Email Service 基础结构自动生成的。您无法设置或覆盖它们。如果您在 headers 对象中包含其中任何一个，API 会返回 E_HEADER_NOT_ALLOWED。
| 标头 | 行为 |
|---|---|
Date |
接收时设置的 UTC 时间戳 |
Message-ID |
与 Cloudflare 域一起生成以进行唯一跟踪 |
MIME-Version |
始终为 1.0 |
Content-Type |
根据提供的正文部分生成 |
Content-Transfer-Encoding |
根据内容分析生成 |
DKIM-Signature |
由 Cloudflare 基础结构签名 |
Return-Path |
设置为 Cloudflare 退信处理程序 |
Received |
根据 RFC 5321 在每一跳添加 |
Feedback-ID |
为 Google Postmaster Tools 信誉反馈生成 |
ARC-* |
用于转发的身份验证链 |
TLS-Required |
平台控制的传输基础结构设置 |
TLS-Report-Domain |
TLS 失败报告路由到 Cloudflare 基础结构 |
TLS-Report-Submitter |
引用 Cloudflare 发送域 |
CFBL-Address |
投诉反馈循环地址 (RFC 9477) |
CFBL-Feedback-ID |
投诉反馈循环 ID (RFC 9477) |
与一等 API 字段相对应的标头 —— From、To、Cc、Bcc、Subject、Reply-To —— 也将在 headers 对象中被拒绝并返回 E_HEADER_USE_API_FIELD。请改用专门的 API 字段（Workers 的 from、to、cc、bcc、subject、replyTo / REST 的 reply_to）来设置这些内容。
这些标头可以通过 headers 字段设置。任何未在此列出且不以 X- 开头的标头都将被拒绝并返回 E_HEADER_NOT_ALLOWED。
| 标头 | RFC | 备注 |
|---|---|---|
In-Reply-To |
RFC 5322 ↗ | 对于所有客户端中的电子邮件线程至关重要 |
References |
RFC 5322 ↗ | 对于所有客户端中的电子邮件线程至关重要 |
| 标头 | RFC | 备注 |
|---|---|---|
List-Unsubscribe |
RFC 2369 ↗ | 必须包含 <https://...> 和/或 <mailto:...> URI。HTTP（非 TLS）URI 将被拒绝。Gmail 和 Yahoo 要求批量发送者提供此项。始终根据 RFC 8058 具有 DKIM 签名。 |
List-Unsubscribe-Post |
RFC 8058 ↗ | 必须完全是 List-Unsubscribe=One-Click（区分大小写）。需要带有 HTTPS URI 的 List-Unsubscribe。 |
List-Id |
RFC 2919 ↗ | 列表标识 |
List-Archive |
RFC 2369 ↗ | 列表归档的 URL |
List-Help |
RFC 2369 ↗ | 帮助的 URL |
List-Owner |
RFC 2369 ↗ | 列表所有者的联系方式 |
List-Post |
RFC 2369 ↗ | 发布的地址 |
List-Subscribe |
RFC 2369 ↗ | 订阅 URL 或地址 |
Precedence |
事实标准 | 接受的值：bulk、list、junk |
| 标头 | RFC | 备注 |
|---|---|---|
Auto-Submitted |
RFC 3834 ↗ | 值：auto-generated、auto-replied、auto-notified |
| 标头 | RFC | 备注 |
|---|---|---|
Content-Language |
RFC 3282 ↗ | 内容语言（例如 en、fr） |
Keywords |
RFC 5322 ↗ | 消息关键字（对于多个值，以逗号分隔） |
Comments |
RFC 5322 ↗ | 附加注释（对于多个值，以逗号分隔） |
Importance |
RFC 2156 ↗ | 值：high、normal、low |
Sensitivity |
RFC 2156 ↗ | 值：personal、private、company-confidential |
Organization |
RFC 4021 ↗ | 发件人组织名称 |
| 标头 | RFC | 备注 |
|---|---|---|
Require-Recipient-Valid-Since |
RFC 7293 ↗ | 地址重用保护 |
| 标头 | RFC | 备注 |
|---|---|---|
Archived-At |
RFC 5064 ↗ | 消息被归档的 URL |
允许任何以 X- 开头的标头。这涵盖了常见的标头，如 X-Mailer、X-Priority、X-Campaign-ID，以及您的应用程序所需的任何自定义跟踪标头。
- 名称格式：
X-[A-Za-z0-9\-_]+，最长 100 个字符 - 值： UTF-8，最多 2,048 字节
- 不限制 X-标头的数量（受 16 KB 总有效负载限制）
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": "user@example.com",
"from": "notifications@yourdomain.com",
"subject": "Your weekly digest",
"html": "<h1>Weekly Digest</h1>",
"headers": {
"In-Reply-To": "<original-message-id@yourdomain.com>",
"References": "<original-message-id@yourdomain.com>",
"List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=abc123>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
"X-Campaign-ID": "weekly-digest-2026-03",
"X-User-Segment": "premium"
}
}'const response = await env.EMAIL.send({
to: "user@example.com",
from: "notifications@yourdomain.com",
subject: "Your weekly digest",
html: "<h1>Weekly Digest</h1>",
headers: {
// Threading
"In-Reply-To": "<original-message-id@yourdomain.com>",
References: "<original-message-id@yourdomain.com>",
// List management (required by Gmail/Yahoo for bulk senders)
"List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=abc123>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
// Custom tracking
"X-Campaign-ID": "weekly-digest-2026-03",
"X-User-Segment": "premium",
},
});| 限制 | 值 |
|---|---|
| 最大的允许列表（非 X）自定义标头数量 | 20 |
| 标头名称最大长度 | 100 字节 |
| 标头值最大长度 | 2,048 字节 |
| 自定义标头的总有效负载 | 16 KB |
所有自定义标头的总有效负载计算方式为 sum(len(name) + 2 + len(value) + 2)（即：名称 + : + 值 + CRLF）。允许列表的标头和 X-标头将一起计入此限制。
- 标头名称 — 仅限 ASCII，无空格，无冒号，1–100 个字符。允许列表的标头必须匹配
[A-Za-z0-9\-]+。X-标头必须匹配X-[A-Za-z0-9\-_]+（仅允许在 X-标头中使用下划线）。 - 标头值 — 允许使用 UTF-8，最多 2,048 字节，无裸 CR/LF。拒绝空值。
- 不区分大小写匹配 — 根据 RFC 5322 §2.2 ↗，标头名称的匹配不区分大小写。生成的邮件中使用允许列表的规范大小写形式。
- 正确的行折叠 — 超过 78 个字符的过长标头将使用 CRLF+WSP 而非 MIME 编码根据 RFC 5322 折叠。
- 单次出现 —
headers类型为{ [key]: string }，因此每个标头名称最多可以出现一次。对于支持多个值（如Keywords或Comments）的标头，请在一个字符串中使用逗号分隔值。
| 错误代码 | 条件 | 示例消息 |
|---|---|---|
E_HEADER_NOT_ALLOWED |
标头受平台控制或不在允许列表中 | Header 'Date' is not allowed. It is auto-generated by the platform. |
E_HEADER_USE_API_FIELD |
标头对应一等 API 字段 | Header 'From' must be set via the 'from' API field, not the 'headers' object. |
E_HEADER_VALUE_INVALID |
标头值格式不正确或为空 | Header 'List-Unsubscribe' must contain angle-bracket HTTPS or mailto URI(s). |
E_HEADER_VALUE_TOO_LONG |
标头值超过 2,048 字节限制 | Header 'X-Campaign-ID' value exceeds 2048 byte limit. |
E_HEADER_NAME_INVALID |
标头名称包含无效字符或超过 100 字节 | Header name 'Bad Header!' contains invalid characters. |
E_HEADERS_TOO_LARGE |
自定义标头的总有效负载超过 16 KB | Total custom headers payload (17.2KB) exceeds 16KB limit. |
E_HEADERS_TOO_MANY |
提供的允许列表（非 X）自定义标头太多 | 21 allowlisted headers provided, maximum is 20. |