Email headers

When sending emails with Cloudflare Email Service, you can set custom headers using the headers field in the Workers API or REST API. The Email Service uses a allowlist-based approach — only explicitly approved headers are accepted. Any header not on the allowlist (and not an X- prefixed custom header) is rejected at API time with a clear error.

When sending over SMTP, set headers directly in the MIME message rather than through a headers field. The same allowlist applies.

These headers are auto-generated by the Cloudflare Email Service infrastructure. You cannot set or override them. If you include any of these in the headers object, the API returns E_HEADER_NOT_ALLOWED.

Headers that correspond to first-class API fields — From, To, Cc, Bcc, Subject, Reply-To — are also rejected in the headers object with E_HEADER_USE_API_FIELD. Set these using the dedicated API fields (from, to, cc, bcc, subject, replyTo for Workers / reply_to for REST) instead.

These headers can be set via the headers field. Any header not listed here and not starting with X- is rejected with E_HEADER_NOT_ALLOWED.

Any header starting with X- is allowed. This covers common headers like X-Mailer, X-Priority, X-Campaign-ID, and any custom tracking headers your application needs.

• Name format: X-[A-Za-z0-9\-_]+, maximum 100 characters
• Value: UTF-8, maximum 2,048 bytes
• No count limit on X-headers (subject to the 16 KB total payload limit)

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",
	},
});

The total payload is calculated as sum(len(name) + 2 + len(value) + 2) for all custom headers (name + : + value + CRLF). Allowlisted and X-headers are counted together toward this limit.

1. Header names — ASCII only, no spaces, no colons, 1–100 characters. Allowlisted headers must match [A-Za-z0-9\-]+. X-headers must match X-[A-Za-z0-9\-_]+ (underscores allowed only in X-headers).
2. Header values — UTF-8 allowed, maximum 2,048 bytes, no bare CR/LF. Empty values are rejected.
3. Case-insensitive matching — Header names are matched case-insensitively per RFC 5322 §2.2 ↗. The canonical casing from the allowlist is used in the generated message.
4. Proper line folding — Long headers are folded at 78 characters per RFC 5322 using CRLF+WSP, not MIME encoding.
5. Single occurrence — The headers type is { [key]: string }, so each header name can appear at most once. For headers that support multiple values (such as Keywords or Comments), use comma-separated values in a single string.