← Cloudflare Email Service / email-service / reference

Заголовки писем

При отправке писем через Cloudflare Email Service можно задать пользовательские заголовки с помощью headers поле в API Workers или REST API. Email Service использует подход на основе allowlist : принимаются только явно разрешённые заголовки. Любой заголовок, не входящий в список разрешённых (и не являющийся X- с этим префиксом) отклоняется на уровне API с понятным сообщением об ошибке.

При отправке через SMTP, задавайте заголовки непосредственно в MIME-сообщении, а не через headers поле. Действует тот же список разрешённых значений.

Эти заголовки автоматически создаются инфраструктурой Cloudflare Email Service. Задать или переопределить их нельзя. Если вы укажете любой из них в headers объект, API возвращает E_HEADER_NOT_ALLOWED.

Заголовки, которые соответствуют основным полям API: From, To, Cc, Bcc, Subject, Reply-To : также отклоняются в headers объект с E_HEADER_USE_API_FIELD. Задайте их через специальные поля API (from, to, cc, bcc, subject, replyTo для Workers / reply_to для REST) вместо этого.

Эти заголовки можно задать через headers поле. Любой заголовок, который не указан здесь и не начинается с X- отклоняется с E_HEADER_NOT_ALLOWED.

Если запрос на отправку содержит запрещённый заголовок, Email Service отклоняет весь запрос целиком, а не удаляет заголовок и продолжает отправку.

Любой заголовок, начинающийся с X- разрешён. Это касается таких распространённых заголовков, как X-Mailer, X-Priority, X-Campaign-ID, а также любые пользовательские заголовки отслеживания, необходимые вашему приложению.

• Формат имени: X-[A-Za-z0-9\-_]+, максимум 100 символов
• Значение: UTF-8, максимум 2,048 байт
• Без ограничения по количеству для X-заголовков (с учётом общего ограничения на размер полезной нагрузки в 16 КБ)

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": {
      "In-Reply-To": "<[email protected]>",
      "References": "<[email protected]>",
      "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: "[email protected]",
	from: "[email protected]",
	subject: "Your weekly digest",
	html: "<h1>Weekly Digest</h1>",
	headers: {
		// Threading
		"In-Reply-To": "<[email protected]>",
		References: "<[email protected]>",

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

Общий размер полезной нагрузки рассчитывается как sum(len(name) + 2 + len(value) + 2) для всех пользовательских заголовков (имя + : + value + CRLF). Заголовки из списка разрешённых и X-заголовки учитываются в этом лимите совместно.

1. Имена заголовков : только ASCII, без пробелов и двоеточий, от 1 до 100 символов. Разрешённые заголовки должны соответствовать [A-Za-z0-9\-]+. X-заголовки должны соответствовать X-[A-Za-z0-9\-_]+ (подчёркивания допускаются только в X-заголовках).
2. Значения заголовков : допускается UTF-8, максимум 2,048 байт, отдельные CR/LF запрещены. Пустые значения отклоняются.
3. Сопоставление без учета регистра : имена заголовков сравниваются без учёта регистра согласно RFC 5322 §2.2 ↗. В создаваемом письме используется исходный регистр символов из списка разрешенных адресов.
4. Корректное сворачивание строк : длинные заголовки переносятся через 78 символов согласно RFC 5322 с помощью CRLF+WSP, а не кодированием MIME.
5. Единичный случай : headers имеет тип { [key]: string }, поэтому каждое имя заголовка может встречаться не более одного раза. Для заголовков, поддерживающих несколько значений (например, Keywords или Comments), используйте значения, разделённые запятыми, в одной строке.