name: mailchannels-email-api
description: 通过 MailChannels Email API 发送邮件，并将签名的投递事件 Webhook 数据摄入 Clawdbot (Moltbot)。
homepage: https://docs.mailchannels.net/email-api/
metadata: {"moltbot":{"emoji":"📨","requires":{"env":["MAILCHANNELS_API_KEY","MAILCHANNELS_ACCOUNT_ID"],"bins":["curl"]},"primaryEnv":"MAILCHANNELS_API_KEY"}}

MailChannels Email API（发送邮件 + 投递事件）

环境变量

必需：
- MAILCHANNELS_API_KEY（在 X-Api-Key 请求头中发送）
- MAILCHANNELS_ACCOUNT_ID（即 customer_handle）

可选：
- MAILCHANNELS_BASE_URL（默认值：https://api.mailchannels.net/tx/v1）
- MAILCHANNELS_WEBHOOK_ENDPOINT_URL

域名锁定（DNS 配置）

为每个发件域名创建一条 TXT 记录：
- 主机名：_mailchannels.<你的域名>
- 记录值：v=mc1; auid=<你的账户ID>

API 快速参考

基础 URL：${MAILCHANNELS_BASE_URL:-https://api.mailchannels.net/tx/v1}
- 发送邮件：POST /send
- 异步发送：POST /send-async
- Webhook 管理：POST /webhook?endpoint=<url>、GET /webhook、DELETE /webhook、POST /webhook/validate
- 获取公钥：GET /webhook/public-key?id=<keyid>

发送邮件

请求负载至少需包含：personalizations、from、subject、content。
- 常规流量使用 /send 端点。
- 队列化/低延迟场景使用 /send-async 端点。
- 两者均会生成 Webhook 事件。
- 请持久化 MailChannels 的相关 ID（如 request_id）。

投递事件（Webhook）

MailChannels 会 POST 一个 JSON 数组。常见字段包括：email、customer_handle、timestamp、event、request_id。
退信事件通常包含：recipients、status、reason、smtp_id。

Moltbot Webhook 路由配置

1) 在 ~/.clawdbot/moltbot.json 中启用 Webhook。
2) 通过 hooks.mappings 将 /hooks/<路径> 映射到代理动作，并可选择进行数据转换。
3) 在 MailChannels 中注册你的公共端点：/webhook?endpoint=...。

Webhook 签名验证

需检查的请求头：Content-Digest、Signature-Input、Signature。
验证步骤：
1. 解析 Signature-Input 头（获取 name、created、alg、keyid）。
2. 拒绝过时的 created 时间戳。
3. 根据 keyid 获取公钥。
4. 按照 RFC 9421 规范重建签名基字符串。
5. 验证 ed25519 签名（避免自行实现）。
6. 同时验证 JSON 主体是否为数组，并确保每个事件的 customer_handle 等于 MAILCHANNELS_ACCOUNT_ID。

关联 ID 与状态更新

• 存储你的内部消息 ID 以及 MailChannels 的 ID（如 request_id、smtp_id）。
• 根据事件更新投递状态：processed（已处理）、delivered（已投递）、soft-bounced（软退信）、hard-bounced（硬退信）、dropped（已丢弃）。
• 操作建议：快速返回 2xx 响应、异步处理事件、存储原始事件数据、对重试请求进行去重。