邮件发送接口规范 0.1.0

本包让应用经已授权的邮件发送绑定寄出单个收件人的纯文字邮件。发送文字邮件 的参数依次是邮件绑定名、发件地址、收件地址、主题和正文，返回 （爻 合 字符串）：成功是（阳，空字符串）；任何失败都是（阴，简短原因），不抛异常，应用据此决定回滚状态或提示用户。简短原因是本包给出的固定中文说明，绝不含地址、主题、正文、令牌或平台的原始消息，因此可以安全地写进日志或界面。

校验

下列校验由本包在调用平台之前强制；任何一项失败都返回（阴，原因）且不调用平台，按表中顺序，先失败的先返回：

| 条件 | 返回的原因 | | --- | --- | | 发件地址不合法 | 发件地址无效 | | 收件地址不合法 | 收件地址无效 | | 主题不合法 | 邮件主题无效 | | 正文不合法 | 邮件正文无效 |

• 地址（发件与收件规则相同）：3 至 254 个 UTF-8 字节；恰含一个 @ 且不在首尾；不含 ASCII 空格与控制字符、DEL、C1 控制字符，不含空白类与不可见格式字符（NBSP U+00A0、U+1680、U+2000 至 U+200F、U+2028 至 U+202F、U+205F 至 U+206F、U+3000、U+FEFF），也不含 "、(、)、,、:、;、<、>、[、]、\。这些规则使它只能是单个收件人，不能夹带显示名、多个收件人或换行注入。
• 主题：至多 200 字节；不含 C0 控制字符（含 CR、LF 与制表）、DEL、U+0085、U+2028、U+2029；可以为空。
• 正文：至多 1 MiB（1048576 字节）；除制表、换行、回车之外不含 C0 控制字符（含 NUL）；可以为空。

平台交付

校验通过后，本包调用绑定的 send，传入形如 {from, to, subject, text} 的对象。send 同步抛出或异步拒绝都算失败，原因为 邮件发送失败；若平台错误有由字母、数字、下划线、点、美元符、连字符组成且不超过 64 字符的名称，则形如 邮件发送失败：TypeError。错误的消息文字一律不转述，因为它可能含地址或令牌。send 正常完成即成功，本包不读取其返回值。

绑定名由应用传入，由宿主许可（例如 {"EMAIL":["EMAIL"]}）核对：未授权的名称是部署错误，宿主直接中止当前请求。名称已获授权但当前部署没有配置该绑定，或绑定没有 send 方法时，返回（阴，邮件服务未配置）而不是抛异常，使开发和测试环境在没有邮件服务时可以继续运行。发件地址必须落在部署配置的 allowed_sender_addresses 之内，这由平台强制而不是本包；越权发送被平台拒绝，表现为一次失败返回。

一致性样例

| 输入 | 必须观察到 | | --- | --- | | 合法的发件、收件、主题、正文，平台接受 | 返回（阳，空字符串）；平台恰收到一次 send，对象只含 from、to、subject、text 四个字段且与输入逐字相同 | | 平台同步抛出，或异步拒绝，错误消息里含收件地址与令牌 | 返回（阴，邮件发送失败： 加错误名称）；返回的文字不含地址和令牌 | | 收件地址含 CR、LF、空格、逗号、第二个 @ 或尖括号 | 返回（阴，收件地址无效）；平台未被调用 | | 主题含 CR 或 LF（例如 a\r\nBcc: x@y.z） | 返回（阴，邮件主题无效）；平台未被调用 | | 正文恰 1 MiB / 多 1 字节 | 前者成功，后者返回（阴，邮件正文无效） | | 已授权的绑定名在部署里没有配置 | 返回（阴，邮件服务未配置），不抛异常 | | 未授权的绑定名 | 宿主中止当前请求 |

边界

本包只寄纯文字邮件：不提供 HTML 正文、附件、抄送、密送、回复地址、自定义标头，也不提供发送状态查询、重试、限流或去重。这些属于应用：例如应用在保存了一次性令牌之后邮件发送失败，应自行撤销该令牌；应用也不得把收件地址、令牌或邮件正文写进日志。云工适配把接口映射到 Cloudflare 的邮件发送绑定；其他平台可以用等价的服务，只要参数校验、返回值与不泄露原因的规则一致。