← Cloudflare Email Service / email-service / reference

E-mailové hlavičky

Při odesílání e-mailů pomocí služby Cloudflare Email Service můžete nastavit vlastní hlavičky pomocí headers v Workers API nebo REST API. Email Service používá přístup založený na allowlistu : přijímají se pouze explicitně schválená záhlaví. Jakékoli záhlaví, které není na seznamu povolených (a není X- předponou vlastní hlavička) je odmítnuta již na úrovni API s jasnou chybovou zprávou.

Při odesílání přes SMTP, nastavte hlavičky přímo ve zprávě MIME, a ne prostřednictvím headers pole. Platí stejný seznam povolených hodnot.

Tyto hlavičky automaticky generuje infrastruktura Cloudflare Email Service. Nelze je nastavit ani přepsat. Pokud některou z nich uvedete v headers objekt, API vrací E_HEADER_NOT_ALLOWED.

Hlavičky odpovídající standardním polím API, From, To, Cc, Bcc, Subject, Reply-To : jsou také odmítnuty v headers objekt s E_HEADER_USE_API_FIELD. Nastavte je pomocí vyhrazených polí API (from, to, cc, bcc, subject, replyTo pro Workers / reply_to pro REST).

Tyto hlavičky lze nastavit prostřednictvím headers pole. Jakákoli hlavička, která zde není uvedena a nezačíná na X- je odmítnuto s E_HEADER_NOT_ALLOWED.

Pokud požadavek na odeslání obsahuje nepovolenou hlavičku, Email Service celý požadavek odmítne. Hlavičku neodstraní a zprávu neodešle dál.

Jakákoli hlavička začínající na X- je povoleno. To zahrnuje běžné hlavičky jako X-Mailer, X-Priority, X-Campaign-ID, a jakékoli vlastní sledovací hlavičky, které vaše aplikace potřebuje.

• Formát názvu: X-[A-Za-z0-9\-_]+, maximálně 100 znaků
• Hodnota: UTF-8, maximálně 2,048 bajtů
• Bez limitu počtu na X-hlavičkách (v rámci celkového limitu payloadu 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": "[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",
	},
});

Celkový payload se počítá jako sum(len(name) + 2 + len(value) + 2) pro všechny vlastní hlavičky (název + : + hodnota + CRLF). Hlavičky ze seznamu povolených a hlavičky X se do tohoto limitu započítávají společně.

1. Názvy hlaviček : pouze ASCII, žádné mezery, žádné dvojtečky, 1-100 znaků. Povolené záhlaví musí odpovídat [A-Za-z0-9\-]+. X-hlavičky musí odpovídat X-[A-Za-z0-9\-_]+ (podtržítka jsou povolena pouze v hlavičkách X).
2. Hodnoty hlaviček : povoleno UTF-8, maximálně 2,048 bajtů, žádné samostatné CR/LF. Prázdné hodnoty se odmítají.
3. Porovnávání bez rozlišování velkých a malých písmen : Názvy záhlaví se porovnávají bez rozlišení velkých a malých písmen podle RFC 5322 §2.2 ↗. Ve vygenerované zprávě se použije zápis velkých a malých písmen tak, jak je uvedený v allowlistu.
4. Správné zalamování řádků : Dlouhá záhlaví se zalamují na 78 znaků podle RFC 5322 pomocí CRLF+WSP, nikoli pomocí kódování MIME.
5. Jediný výskyt : headers typ je { [key]: string }, takže se každý název hlavičky může objevit nejvýše jednou. U hlaviček, které podporují více hodnot (například Keywords nebo Comments), použijte hodnoty oddělené čárkami v jednom řetězci.