HTTP 契约、安全边界与扩展 FAQ
本页定义了业务端与历史面板接入 Cloudflare Email Relay 时需要遵守的全部 HTTP 协议、字段格式、鉴权与响应错误码契约。
端点一览与请求外框限制
| 路径 | 方法 | 用途与适用调用方 |
|---|---|---|
/v1/send | POST | 标准发信接口:所有新接入服务、脚本与 CI 流水线统一使用此端点 |
/v1/panel | POST | 兼容面板接口:仅供固定发 {token, from, fromName, to, title, msg, type} 且无法设置请求头的历史面板使用 |
/healthz | GET / HEAD | 就绪体检探针:返回服务配置与绑定可用性布尔清单(不回显配置值) |
所有发信请求(/v1/send 与 /v1/panel)必须在进入业务逻辑前满足以下外框约定:
- 禁止 URL query 参数:任何
?foo=bar均返回400 invalid_request。 - 媒体类型与编码:
Content-Type必须为application/json(允许带参数如; charset=utf-8),否则返回415 unsupported_media_type;不得带压缩Content-Encoding(仅允许省略或identity),否则返回415 unsupported_content_encoding。 - 请求体体积与严格 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 | 否 | 共享总收件人上限;跨字段不区分大小写禁止重复邮箱 |
subject | string | 是 | 非空(去空白后非空)、<= 256 UTF-8 字节、禁止所有控制字符(含换行/回车)及双向/零宽字符 |
text | string | 条件必填* | 非空、<= 96 KiB、允许换行 \n,禁止 \0 空字节 |
html | string | 条件必填* | 非空、<= 96 KiB,规则同 text;text 与 html 至少提供一项 |
replyTo | 同 from | 否 | 域名同样受 ALLOWED_SENDER_DOMAINS 约束 |
邮箱地址与显示名细则:
- 邮箱总长
<= 254字节、本地部分<= 64字节(不允许首尾点号、连续..与空白),域名自动归一化为小写且至少包含一个.。 - 可选显示名
name(或面板fromName)必须非空且<= 128UTF-8 字节,禁止包含<、>、"、\四个地址定界符,防止伪造发件人显示格式。
面板兼容报文(POST /v1/panel)
固定允许 7 个字段:token、from、fromName、to、title、msg、type:
title映射为邮件subject(<= 256UTF-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。
// 成功响应(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 |
400 | invalid_request | 带 query、非 UTF-8、坏 JSON、非对象或空体 | X-Request-Id |
400 | invalid_field | 字段类型/长度/域/重复/未知字段违规 | error.field(如 to[1]、from.name) |
400 | credentials_ambiguous | /v1/panel 同时在头和 body 提供了令牌 | — |
401 | unauthorized | 缺少有效 Bearer 或令牌不匹配 | WWW-Authenticate: Bearer realm="email-relay" |
403 | forbidden | 来源 IP 不在白名单,或缺少 CF-Connecting-IP | — |
404 | not_found | 未知请求路径 | — |
405 | method_not_allowed | 请求方法不支持 | Allow: POST 或 Allow: GET, HEAD |
413 | payload_too_large | 请求体超过 128 KiB | — |
415 | unsupported_media_type / unsupported_content_encoding | 非 application/json 或携带压缩编码 | — |
429 | rate_limited | 触发 RATE_LIMITER 限流 | Retry-After: 60 |
502 | upstream_failed | 平台 EMAIL.send 拒收或异常 | error.details.providerCode(截断至 64 字符) |
503 | not_configured | 服务端配置缺失/非法,或绑定损坏 | /healthz 额外附带 error.details.checks |
500 | internal_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")。
进一步深入请求执行链路与源码结构,请阅读 请求链路与交互架构图 与 源码地图与开发验证。