Skip to content

HTTP 契约、安全边界与扩展 FAQ ​

本页定义了业务端与历史面板接入 Cloudflare Email Relay 时需要遵守的全部 HTTP 协议、字段格式、鉴权与响应错误码契约。

端点一览与请求外框限制 ​

路径方法用途与适用调用方
/v1/sendPOST标准发信接口:所有新接入服务、脚本与 CI 流水线统一使用此端点
/v1/panelPOST兼容面板接口:仅供固定发 {token, from, fromName, to, title, msg, type} 且无法设置请求头的历史面板使用
/healthzGET / HEAD就绪体检探针:返回服务配置与绑定可用性布尔清单(不回显配置值)

所有发信请求(/v1/send 与 /v1/panel)必须在进入业务逻辑前满足以下外框约定:

  1. 禁止 URL query 参数:任何 ?foo=bar 均返回 400 invalid_request。
  2. 媒体类型与编码:Content-Type 必须为 application/json(允许带参数如 ; charset=utf-8),否则返回 415 unsupported_media_type;不得带压缩 Content-Encoding(仅允许省略或 identity),否则返回 415 unsupported_content_encoding。
  3. 请求体体积与严格 UTF-8:流式读取并累加字节,超过 128 KiB 立刻取消读取返回 413 payload_too_large;必须为合法 UTF-8 JSON 对象(非数组、字符串或空体),否则返回 400 invalid_request。

鉴权、来源验证与多令牌轮换 ​

请求按 配置加载 → 来源头 CF-Connecting-IP 与白名单 → 可选 RATE_LIMITER 限流 → 有界 JSON 读取 → 令牌校验 的严格顺序执行。把字段级校验放在鉴权之后,可以防止未认证调用方借助 400 invalid_field 探测允许发件域或字段白名单。

令牌格式与比对机制 ​

  • 请求头传递:Authorization: Bearer <token>(Bearer 方案名大小写不敏感;Basic 或空 Bearer 视为未提供令牌)。
  • 面板降级路径:仅 /v1/panel 允许在 Authorization 未提供 Bearer 令牌时读取 JSON 体内的 token 字段;若同时在请求头与 body 中都传入了令牌,服务端不猜测优先级,直接返回 400 credentials_ambiguous。
  • 令牌格式约束:必须符合 [A-Za-z0-9._~+/=-] 且长度在 32 至 512 字符之间;格式不合规的令牌在比对前直接视为空串而不进入哈希循环。
  • 零停机轮换操作:AUTH_TOKENS 支持以英文逗号分隔配置多把令牌。tokenMatches 先对候选串与每一把配置令牌分别做 SHA-256 摘要,再逐字节异或比对全部配置项而不提前返回。轮换流程为:先在 AUTH_TOKENS 追加新令牌 → 灰度切换所有调用方 → 确认旧令牌不再使用后将其从 AUTH_TOKENS 移除。

报文字段 Schema 与字节上限 ​

两套接口均严格白名单化:出现表外未知字段(如把 cc 误拼为 ccs,或在 /v1/send 中传入 token)会立刻返回 400 invalid_field,绝不静默忽略。所有长度上限均按 UTF-8 编码后的字节数 计算(中文每字占 3 字节)。

标准报文(POST /v1/send) ​

字段类型必填上限与校验规则
from"a@b.c" 或 { email, name? }是域名必须匹配 ALLOWED_SENDER_DOMAINS
to单地址或非空地址数组是与 cc/bcc 共计不超过 MAX_RECIPIENTS(默认 10,最大 50)
cc / bcc同 to否共享总收件人上限;跨字段不区分大小写禁止重复邮箱
subjectstring是非空(去空白后非空)、<= 256 UTF-8 字节、禁止所有控制字符(含换行/回车)及双向/零宽字符
textstring条件必填*非空、<= 96 KiB、允许换行 \n,禁止 \0 空字节
htmlstring条件必填*非空、<= 96 KiB,规则同 text;text 与 html 至少提供一项
replyTo同 from否域名同样受 ALLOWED_SENDER_DOMAINS 约束

邮箱地址与显示名细则:

  • 邮箱总长 <= 254 字节、本地部分 <= 64 字节(不允许首尾点号、连续 .. 与空白),域名自动归一化为小写且至少包含一个 .。
  • 可选显示名 name(或面板 fromName)必须非空且 <= 128 UTF-8 字节,禁止包含 <、>、"、\ 四个地址定界符,防止伪造发件人显示格式。

面板兼容报文(POST /v1/panel) ​

固定允许 7 个字段:token、from、fromName、to、title、msg、type:

  • title 映射为邮件 subject(<= 256 UTF-8 字节);
  • msg 映射为纯文本正文 text;当 type 存在(<= 128 字节)且值不为 "text" 时,正文会被拼装为 通知类型:<type>\n\n<msg>,拼装后总字节数仍不得超过 96 KiB;
  • fromName 映射为 from.name(同样受 128 字节与 < > " \ 禁令限制)。

统一响应信封、错误码与日志契约 ​

所有响应统一包含 Content-Type: application/json; charset=utf-8、X-Request-Id、Cache-Control: no-store、X-Content-Type-Options: nosniff、Content-Security-Policy: default-src 'none' 与 Referrer-Policy: no-referrer。

json
// 成功响应(200 OK)
{
  "ok": true,
  "requestId": "8fcea792-6e49-411e-a386-ffabd65c386b",
  "data": {
    "messageId": "mid-1",
    "accepted": { "to": ["ops@example.org"], "cc": [], "bcc": [] }
  }
}

// 失败响应示例(400 invalid_field)
{
  "ok": false,
  "requestId": "91b2...",
  "error": {
    "code": "invalid_field",
    "message": "is not allowed",
    "field": "ccs"
  }
}

HTTP 状态码与 error.code 对照表 ​

HTTP 状态error.code归属与含义附带结构 / 响应头
200—已交付平台 EMAIL.send 受理data.messageId、data.accepted
400invalid_request带 query、非 UTF-8、坏 JSON、非对象或空体X-Request-Id
400invalid_field字段类型/长度/域/重复/未知字段违规error.field(如 to[1]、from.name)
400credentials_ambiguous/v1/panel 同时在头和 body 提供了令牌—
401unauthorized缺少有效 Bearer 或令牌不匹配WWW-Authenticate: Bearer realm="email-relay"
403forbidden来源 IP 不在白名单,或缺少 CF-Connecting-IP—
404not_found未知请求路径—
405method_not_allowed请求方法不支持Allow: POST 或 Allow: GET, HEAD
413payload_too_large请求体超过 128 KiB—
415unsupported_media_type / unsupported_content_encoding非 application/json 或携带压缩编码—
429rate_limited触发 RATE_LIMITER 限流Retry-After: 60
502upstream_failed平台 EMAIL.send 拒收或异常error.details.providerCode(截断至 64 字符)
503not_configured服务端配置缺失/非法,或绑定损坏/healthz 额外附带 error.details.checks
500internal_error未预期内部异常—

结构化日志采用单行 JSON(level、event、requestId 及安全附注如 route、recipients、messageId、providerCode),永久屏蔽原始令牌、错误配置取值与邮件正文。

扩展开发与常见坑 FAQ ​

Q:为什么接口返回的 error.message 是英文,而源码注释和文档是中文?error.message 属于稳定的对外契约,部分调用方会按字面字符串断言错误类型(如 Request body must be valid UTF-8),改动英文错误文本会破坏下游兼容。

Q:如果想扩展支持附件(attachments)或自定义邮件头,需要注意什么? 当前 STANDARD_FIELDS 有意拒收这两者。若未来确实需要扩展,必须在 src/validate.ts 中同步新增:① 邮件头名/值的 CRLF 与控制字符防注入检查(自定义头);② 附件数量、单件与总载荷体积上限(MAX_REQUEST_BYTES 仅 128 KiB),并先补齐对应 Vitest 边界用例。

Q:为什么我往 /v1/send 的 body 里传了 token,却收到 401 而不是 400 invalid_field?/v1/send 只读取 Authorization 请求头中的 Bearer 令牌;未通过鉴权时不会进入字段校验,因此不会泄露 token 字段不合法的细节。只有带上有效 Bearer 头后,才会收到 400 invalid_field (field: "token")。

进一步深入请求执行链路与源码结构,请阅读 请求链路与交互架构图 与 源码地图与开发验证。