事件和网络钩子
连接网络钩子
在集成设置中指定接收 Webhook 的地址。它将收到有关新信件、邮箱状态和操作结果的通知。
在集成设置中，设置单独的 Webhook 密钥并启用传递。该秘密用于验证通知签名； mail API-key 不适合此操作。
通知格式
通知来自 HTTP POST- 请求，其中 Content-Type: application/json. 字段 event 包含事件类型、timestamp — 通知时间、data — 事件数据。 data 的组成取决于事件。
标识符 data.event_id 允许您识别重新投递。将其与您的集成 ID 一起存储，并且仅处理一个事件一次。
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}验证与确认
标头 X-Webhook-Signature 包含小写十六进制表示法的 HMAC-SHA256。根据请求正文的原始字节和 Webhook 密钥计算签名。处理数据前检查签名；重新序列化 JSON 将更改正在签名的字节。
验证签名并保存事件后，返回 HTTP 200 或 201。响应 202 和 204 不确认收到。 10秒内回复；保存事件后执行冗长的处理。
通知可能会重复且无序地到达。在更改订阅状态之前，请检查其当前详细信息。集成设置中提供了交付历史记录。
发生什么事件
mailbox.created- 该盒子已创建并可供使用。
mailbox.expiring- 盒子的付费期即将结束。
mailbox.renewed- 盒子的付费期限已延长。
mailbox.suspended- 邮箱访问被暂停：无法读取和发送。
mailbox.resumed- 对邮箱的访问已恢复。
mailbox.deleting_soon- 距离未付费盒子被删除还有一小时。
mailbox.deleted- 该框已被删除。
mailbox.account_changed- 该邮箱已链接到另一个邮件帐户。
mail.message.received- 邮箱中出现了一封新收到的信件。
mail.operation.succeeded- 手术顺利完成。对于发送，这意味着邮件服务器接受信件，而不是递送到收件人的收件箱。
mail.operation.failed- 操作失败。
mail.operation.uncertain- 发送结果未知。请在重新发送前检查状况。
付款提醒：到期前14、7、3、2、1天1小时。续订会取消尚未发送的过时提醒。