メールヘッダー

Cloudflare Email Service でメールを送るとき、Workers API または REST API の headers フィールドでカスタムヘッダーを設定できます。Email Service は 許可リスト方式 です。明示的に許可されたヘッダーだけを受け付けます。許可リストになく、X- プレフィックスのカスタムヘッダーでもないヘッダーは、API 呼び出し時に明確なエラーで拒否されます。

SMTP で送る場合は、headers フィールドではなく MIME メッセージに直接ヘッダーを設定します。同じ許可リストが適用されます。

これらのヘッダーは Cloudflare Email Service のインフラが自動生成します。設定や上書きはできません。headers オブジェクトに含めると、API は E_HEADER_NOT_ALLOWED を返します。

ファーストクラスの 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 で拒否されます。

許可されていないヘッダーが含まれると、Email Service は送信リクエスト全体を拒否します。ヘッダーを取り除いて送信を続けることはありません。

X- で始まるヘッダーはすべて許可されます。X-Mailer、X-Priority、X-Campaign-ID などの一般的なヘッダーや、アプリケーションが必要とするカスタムの追跡ヘッダーも対象です。

• 名前の形式: X-[A-Za-z0-9\-_]+、最大 100 文字
• 値: UTF-8、最大 2,048 バイト
• 件数制限なし（合計ペイロード 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",
	},
});

合計ペイロードは、すべてのカスタムヘッダーについて sum(len(name) + 2 + len(value) + 2)（名前 + : + 値 + CRLF）で計算します。許可リストのヘッダーと X-headers は、この上限にまとめて計上されます。

1. ヘッダー名 — ASCII のみ、スペースなし、コロンなし、1〜100 文字。許可リストのヘッダーは [A-Za-z0-9\-]+ に一致する必要があります。X-headers は X-[A-Za-z0-9\-_]+ に一致する必要があります（アンダースコアは X-headers でのみ許可）。
2. ヘッダー値 — UTF-8 可、最大 2,048 バイト、裸の CR/LF は不可。空の値は拒否されます。
3. 大文字小文字を区別しない照合 — ヘッダー名は RFC 5322 §2.2 ↗ に従い、大文字小文字を区別せず照合します。生成されるメッセージでは、許可リストの正規の大文字小文字を使います。
4. 適切な行折り — 長いヘッダーは RFC 5322 に従い、78 文字で CRLF+WSP を使って折り返します。MIME エンコードは使いません。
5. 単一出現 — headers の型は { [key]: string } のため、各ヘッダー名は最大 1 回です。複数値をサポートするヘッダー（Keywords や Comments など）は、1 つの文字列にカンマ区切りで指定します。