事务邮件 Webhook（2026）：为 Rovela 发信接入投递事件

订阅 Rovela 的事务投递事件（delivered、bounced、complained），校验 x-resend-signature，并正确处理重试——而不必轮询 GET /emails/:id。

事务邮件 Webhook：把投递事件交给你的应用

POST /emails 返回 200，只表示 Rovela 已把邮件入队。它是否投递、延迟、退信，或被标为垃圾邮件，要等其他机器稍后决定。事务邮件 webhook 让你的应用不必轮询就能知道结果。

本文是产品的「投递事件」这一面：该订阅哪些事件、信封、签名和重试。它不是用 Webhook 驱动邮件自动化（把 webhook 当自动化骨架），不是验证 Webhook 签名（只讲验签），也不是入站邮件 API 与 Webhook（入站的 email.received）。权威文档是Webhooks 产品页、概览、事件和安全。

可以从Email API产品页、快速开始、发送邮件 API和身份认证入手。

本系列相关产品指南：

只注册你会处理的事件

curl -X POST https://api.rovela.dev/webhooks   -H "Authorization: Bearer re_your_full_access_key"   -H "Content-Type: application/json"   -d '{
    "endpoint": "https://example.com/hooks/rovela",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'

端点必须是 http 或 https，且不能指向私网或回环地址。响应包含签名密钥，只在创建时展示——请像 Key 一样保存。事件名写错会被拒绝，而不会被静默接受后再也不触发。

空的 events 数组会订阅全部事件，包括以后新增的类型。这在生产里通常不合适。

对事务邮件重要的投递事件

来自事件目录：

事件	含义
`email.sent`	已被 SMTP 中继接受，尚未投递
`email.delivered`	接收服务器已为该收件人接受
`email.delivery_delayed`	仍在重试——不是最终结果
`email.bounced`	永久失败（地址不存在或拒绝收信）
`email.failed`	因非收件人退信的原因失败
`email.suppressed`	发送前被抑制名单拦住
`email.scheduled`	已为将来的 `scheduled_at` 排队
`email.complained`	收件人把邮件标为垃圾邮件

文档建议，email.bounced、email.complained 和 contact.unsubscribed 是最应该在你侧改变状态的三个。email.delivered 常被订阅，但最缺少可执行性——它确认的是通常本就会发生的事。email.opened 和 email.clicked 只在该发信域名开启跟踪时才会触发；关掉跟踪的域名，看起来和「没人互动」的域名一样。

入站到达是 email.received——见入站与出站 Email API。目录里还有广播、联系人、抑制、域名、自动化和 mailbox.quota_alert；只有你会处理时才订阅。

信封与请求头

每个事件都是：

{
  "id": "evt_<uuid>",
  "type": "email.delivered",
  "created_at": "2026-09-25T09:14:02.481+00:00",
  "data": { }
}

投递类 data 包含 email_id、from 和 to。把 data 的字段集视为可追加的——只解析你需要的，忽略其余；否则一个拒绝未知字段的 handler 会永久丢掉事件。

投递时的 HTTP 头（文档中的名称）：

x-resend-signature：t=<unix_timestamp>,v1=<hmac_sha256_hex>
x-resend-event-type
x-resend-delivery-id（这一次尝试，不是事件本身；重试时会变化）

签名是对 "<timestamp>.<raw body>" 做 HMAC-SHA256、以十六进制编码，密钥为该端点的 secret（安全，验证 Webhook 签名）。按事件 id 去重（重试会重复同一 id 和同一 created_at）。需要讨论某一次尝试时，在日志里引用 x-resend-delivery-id。

你必须返回什么

一旦你已接收该事件，就返回 2xx——不必等所有下游做完。把工作放到自己的队列里。重试：总共最多五次，间隔 0 / 1 / 2 / 4 / 8 秒。只有 5xx、408 和 429 会重试。其他 4xx（包括「签名无效 → 400」）会将该次投递标为失败，不再重试。

用 full_access 轮询 GET /emails/:id 或 GET /emails/:id/events 适合排查单封邮件。系统化监控请用 webhook（快速开始）。退信处理见处理退信、退信处理。

FAQ

email.delivered 有多快？ Email API 产品页写明：接收服务器做出决定后，webhook 通常大约在一分钟内推送到（Email API）。

sending_access 能注册 webhook 吗？ 注册 webhook 和读信需要 full_access 或 Dashboard session（身份认证）。

密码重置邮件要订阅打开事件吗？ 通常不必。对退信和投诉采取行动即可；不要让重置流程依赖跟踪像素。

email.suppressed 算退信吗？ 不算。地址在发送前就被拦住了。若抑制是永久性的，你的应用仍应停止向该收件人重试。

订阅结果，而不是靠猜测

用 POST /emails 把邮件入队，再让带签名的 webhook 告诉你是投递了还是退信了。这就是事务邮件的 webhook 闭环：精简的事件列表、校验过的签名、可幂等的 handler。