Skip to content

Cloudflare Email Relay · 接口与契约参考

3 项端点

覆盖 Cloudflare Workers 原生 send_email 绑定发信网关的全部 HTTP 端点:标准 /v1/send、面板兼容 /v1/panel 与七项 /healthz 体检契约。

POSTAuthorization: Bearer + IP 白名单 + 可选 RATE_LIMITER推荐主接入

标准 Bearer HTTP 发信端点

POST /v1/send

按「配置校验 -> CF-Connecting-IP 白名单 -> 限流 -> 128 KiB UTF-8 JSON 读取 -> AUTH_TOKENS 常数时间异或校验 -> 字段校验 -> EMAIL.send」顺序投递纯文本或 HTML 邮件。

查看字段归一化与 11 种错误码 ↗

✅ 能做到

  • AUTH_TOKENS 支持逗号分隔多把密钥,先 SHA-256 再全遍历异或比对实现零停机密钥轮换
  • 按 UTF-8 真实字节精确限制长度;严格在鉴权之后校验发件域,防止未授权 caller 探测 ALLOWED_SENDER_DOMAINS

⛔ 明确限制 / 拒绝条件

  • 不支持 HTML 模板渲染引擎、邮件附件、自定义头部、URL query 参数或压缩请求体(gzip/br 报 415)
  • HTTP 200 仅代表 Cloudflare EMAIL 绑定已受理,不担保收件箱真实送达;wrangler.jsonc 绑定地址校验独立生效

请求头与载荷字段约束

AuthorizationheaderBearer <token>必填

令牌须匹配 ^[A-Za-z0-9._~+/=-]{32,512}$。

from / replyTobodystring | { email, name? }必填

from 域名须在 ALLOWED_SENDER_DOMAINS 内;name <= 128 B 且禁止 < > " \。

to / cc / bccbodyAddress | Address[]必填

三项合计 <= MAX_RECIPIENTS(默认 10、上限 50),跨字段大小写去重冲突即拒收。

subjectbodystring (<= 256 UTF-8 B)必填

trim 后非空,拒绝 CR/LF/控制字符/零宽与双向控制符。

text / htmlbodystring (each <= 96 KiB)必填

至少提供其一(整包请求体硬限 128 KiB),禁止空字节 \0。

响应状态与错误代码

200 OK已提交至 Cloudflare EMAIL.send 绑定并返回规范化收件人回执
400 invalid_field / 401 unauthorized / 403 forbidden字段非法、未知字段、无效/缺失令牌(含 WWW-Authenticate)或 来源 IP 不在白名单
413 payload_too_large / 415 unsupported_* / 429 rate_limited / 502 / 503超 128 KiB、非 application/json、触发 EDGE 限流、上游失败或配置无效(503 not_configured)