MailChannels 电子邮件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用于队列/低延迟；两者均产生网络钩子。 持久化 MailChannels 关联 ID（例如，request_id）。

投递事件（网络钩子）

MailChannels 发送一个 JSON 数组。常见字段：email、customer_handle、timestamp、event、request_id。 退信字段通常包括：recipients、status、reason、smtp_id。

Moltbot 钩子路由

1. 启用钩子在~/.clawdbot/moltbot.json中。
2. 将/hooks/<路径>通过hooks.mappings和可选的转换映射到代理动作。
3. 在MailChannels中注册公共端点/webhook?endpoint=...。

Webhook签名验证

头部：Content-Digest、Signature-Input、Signature。 步骤：

• 解析Signature-Input（名称、创建时间、算法，密钥ID）。
• 拒绝过时的已创建值。
• 通过密钥ID获取公钥。
• 重新创建RFC 9421签名基。
• 验证ed25519签名（避免手动实现）。 同时验证JSON主体是否为数组，且每个事件都具有customer_handle == MAILCHANNELS_ACCOUNT_ID。

关联与状态更新

存储内部消息ID + MailChannels ID（例如，request_id、smtp_id）。 根据事件更新投递状态：已处理、已送达、软退回、硬退信,已丢弃. 操作提示：快速响应2xx状态码，异步处理，存储原始事件，对重试进行去重。