经授权的邮件发送绑定寄出单个收件人的纯文字邮件，成败以返回值表示。
源码浏览已生成；不能解析的文件以纯文本展示，不表示通过类型检查。
# 邮件发送接口规范 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 的邮件发送绑定；其他平台可以用等价的服务，只要参数校验、返回值与不泄露原因的规则一致。
# 邮件发送公约 0.1.0
此包使客经获授之邮件发送绑定，寄一收件人之纯文邮件。`发送文字邮件` 之参依次为邮件绑定名、发件址、收件址、主题与正文，返 `（爻 合 字符串）`：成则（阳，空文）；凡败皆（阴，简短之因），**不抛异**，客据此决回滚其状或告其人。简短之因，乃此包所给之定文，绝不含址、主题、正文、令牌或平台之原辞，故可安书于日志或界面。
## 校验
下列诸校，此包于呼平台之前强行之；一项不合，则返（阴，因）而不呼平台，依表之序，先败者先返：
| 条件 | 所返之因 |
| --- | --- |
| 发件址不合 | `发件地址无效` |
| 收件址不合 | `收件地址无效` |
| 主题不合 | `邮件主题无效` |
| 正文不合 | `邮件正文无效` |
- **址**（发件与收件同则）：三至二百五十四 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），亦不含 `"`、`(`、`)`、`,`、`:`、`;`、`<`、`>`、`[`、`]`、`\`。此诸则使其唯为一收件人，不得夹显示名、多收件人或换行之注。
- **主题**：至多二百字节；不含 C0 控制之字（含 CR、LF 与制表）、DEL、U+0085、U+2028、U+2029；可空。
- **正文**：至多一 MiB（一零四八五七六字节）；除制表、换行、回车外，不含 C0 控制之字（含 NUL）；可空。
## 交付于平台
校验既通，此包呼绑定之 `send`，授以如 `{from, to, subject, text}` 之物。`send` 同步抛出或异步被拒，皆为败，因曰 `邮件发送失败`；若平台之误有名，由字母、数字、下划线、点、美元符、连字符所成，且不逾六十四字，则曰 `邮件发送失败：TypeError` 之类。误之辞一概不述，以其或含址与令牌也。`send` 正常而毕，即为成，此包不读其返值。
绑定名由客授之，由宿主许可（如 `{"EMAIL":["EMAIL"]}`）核之：**未授之名乃部署之误，宿主径止当前请**。名已获授而当前部署未置此绑定，或绑定无 `send` 术，则返（阴，`邮件服务未配置`）而不抛异，使开发与试验之境无邮件服务亦得续行。发件址须在部署所配 `allowed_sender_addresses` 之内，此由平台强制，非此包之事；越权而发者，平台拒之，现为一次败返。
## 一致之例
| 入 | 必见 |
| --- | --- |
| 发件、收件、主题、正文皆合，平台受之 | 返（阳，空文）；平台恰收一次 `send`，其物唯 `from`、`to`、`subject`、`text` 四字段，与所入逐字相同 |
| 平台同步抛出或异步被拒，误辞含收件址与令牌 | 返（阴，`邮件发送失败：` 加误名）；所返之文不含址与令牌 |
| 收件址含 CR、LF、空格、逗号、第二个 `@` 或尖括号 | 返（阴，`收件地址无效`）；平台未被呼 |
| 主题含 CR 或 LF（如 `a\r\nBcc: x@y.z`） | 返（阴，`邮件主题无效`）；平台未被呼 |
| 正文恰一 MiB／多一字节 | 前者成，后者返（阴，`邮件正文无效`） |
| 已授之绑定名而部署未置 | 返（阴，`邮件服务未配置`），不抛异 |
| 未授之绑定名 | 宿主止当前请 |
## 界
此包惟寄纯文邮件：不设 HTML 正文、附件、抄送、密送、回复址、自定标头，亦不设发送状态之查、重试、限流与去重。此皆客之事：如客已存一用之令牌而邮件发送败，当自撤其令牌；亦不得书收件址、令牌或邮件之正文入日志。云工适配以接口映 Cloudflare 之邮件发送绑定；他平台可以等价之服务承之，惟参数之校、返值及不泄因之则须同。