Sign inGet Started

邮件事件

每个收件人在投递过程中推进时,我们都会发出事件。向三个地址发送一封邮件会产生三条独立的事件流,通过 email_id 和 recipient_id 关联。本页定义邮件事件类型。签名、重试、排序和重放请参阅 Webhooks。

每个收件人从 email.accepted 开始,然后是 email.processed。广播收件人本身就是一条独立消息,因此也有自己的 email.accepted,但仅出现在事件 API 和邮件日志中,而非通过 webhook 投递。此后,消息可能被接收服务器接受(email.delivered)、被延迟并重试(email.deferred,最终变为已投递或已退信)、被接收服务器拒绝(email.bounced),或根本未尝试投递(email.rejected)。投递完成后,事件流还可能产生 email.out_of_band_bounce、email.complained、email.opened、email.clicked、email.unsubscribed 和 email.list_unsubscribed。

每个收件人最终处于唯一的终态:delivered、bounced、complained 或 rejected,作为 GET /v1/email/messages/{message_id}/recipients 返回的每收件人 status。互动事件不会改变终态:已打开邮件的收件人仍然是 delivered。延迟退信报告会改变终态,因为接收服务器撤回了先前的接受,收件人从 delivered 变为 bounced。消息整体有自己的汇总状态和各状态计数,见 GET /v1/email/messages/{message_id}。

事件信封

事件以所有 webhook 通用的三字段信封到达:type、timestamp(事件发生时间,RFC 3339 格式)和一个特定于类型的 data 对象。

代码示例
{
  "type": "email.delivered",
  "timestamp": "2026-07-23T14:51:47.107Z",
  "data": {
    "email_id": "em_01ky7qc398fmxraqtxn604zeq9",
    "recipient_id": "er_01ky7qc398fmwsc96nt6anrbqs",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "delivered@messagebird.dev",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null,
    "brand_id": null
  }
}

每个收件人级出站事件都包含 email_id、recipient_id、workspace_id、recipient 地址及其信封 recipient_role(to、cc 或 bcc)。发送时,请保存从工作区和消息 ID 到你自己记录的映射。tags 和 metadata 在可用时携带发送上下文。未提供上下文时它们为 null;对于单次发送的 Bird 退订链接产生的 email.unsubscribed 和 email.list_unsubscribed,它们也为 null。广播退订事件在上下文不可用时也可能返回 null。

broadcast_id 表示该发送所属的广播,在没有广播的发送中为 null。在我们添加该字段之前发出的邮件中,退订链接不包含广播信息,因此无论该邮件是否由广播发出,通过此类链接的退出都会报告 null。请将 email.unsubscribed 和 email.list_unsubscribed 上的 null 视为不确定值。broadcast_id 仅通过 webhook 到达:下方的事件 API 返回的每个事件不包含此字段。各事件类型会添加以下各节中描述的字段。

出站邮件 webhook 还包含可选字段 brand_id。消息事件 API 不包含此字段。

同样的事件也可以事后从 GET /v1/email/messages/{message_id}/events 查询,其中每个事件还额外拥有 id(ev_ 前缀)和 occurred_at。你可以用它来回填、重放或与你的端点收到的数据进行核对。部分字段仅通过该 API 而非 webhook 到达;相关事件描述会逐一说明。

生命周期事件

email.accepted

我们已接受发送并开始准备投递。每个请求的收件人触发一次,是该事件流中的第一个事件。广播收件人也会收到此事件,因为每个收件人都是独立消息,但它只被记录而不投递:请从事件 API 或邮件日志中读取,而非从你的 webhook 端点。载荷:仅包含身份基础字段。

email.processed

消息已构建并排入队列,准备投递到收件人的邮件服务器。载荷:webhook 上仅包含身份基础字段;事件 API 额外提供 mailbox_provider 和 mailbox_provider_region,即接收邮件系统的分类(例如 gmail、NA),在能确定时存在,否则为 null。将此事件的 timestamp 与 email.accepted 的时间戳比较,即可得到我们对单次发送的处理时间。广播没有这样的时间间隔:其接受和处理使用同一个调度时刻,因此两个时间戳相同而不构成处理区间,且接受事件仅通过事件 API 获取,显示为 occurred_at。

email.delivered

接收邮件服务器已接受消息并承担投递责任。此事件并不代表邮件已进入收件箱或已被阅读。Inbox Insights 提供采样的收件箱到达率估算;打开和点击事件记录跟踪请求。载荷:webhook 上仅包含身份基础字段;事件 API 额外提供 sending_ip(消息的发送地址,当可投递性问题追踪到某个 IP 时尤为重要),以及 mailbox_provider 和 mailbox_provider_region。

email.deferred

临时失败:接收服务器要求我们稍后重试(邮箱已满、灰名单、请求速率限制)。我们会自动重试,收件人最终变为 email.delivered 或 email.bounced,因此此事件是信息性的而非终态,收件人可能先被延迟多次。载荷:webhook 上包含 bounce_type、bounce_class、defer_reason(服务器给出的原因)和 sending_ip;事件 API 额外提供 mailbox_provider 和 mailbox_provider_region。

失败事件

email.bounced

SMTP 时的永久失败:接收服务器拒绝了消息,收件人的终态变为 bounced。载荷:bounce_type(见分类表)、bounce_class、bounce_code(SMTP 回复码,例如 550)、bounce_description(服务器给出的原因),以及 webhook 上的 sending_ip;事件 API 额外提供 mailbox_provider 和 mailbox_provider_region。硬退信会屏蔽该地址。

email.out_of_band_bounce

延迟退信:接收服务器在 SMTP 时接受了消息,随后发送了退信报告。其分类方式与 email.bounced 相同(webhook 上包含 bounce_type、bounce_class、bounce_code、bounce_description、sending_ip;事件 API 提供 mailbox_provider 和 mailbox_provider_region)。当报告分类为退信(表中的任一类别)时,说明服务器撤回了先前的接受,收件人从 delivered 变为 bounced。类别不在表中的报告(如自动回复)仅记录在时间线上,不改变状态。硬延迟退信同样会屏蔽该地址。

email.rejected

发给收件人的消息从未到达远程邮件服务器,因此没有尝试投递。这与退信不同:退信是由接收服务器拒绝消息。载荷:rejection_reason,也包含在收件人记录中:

rejection_reason含义
recipient_suppressed收件人被屏蔽列表或已声明的偏好阻止,因此从未尝试投递
transmission_failed消息无法传输以进行投递
generation_failure消息无法构建以进行投递,属于模板或内容问题
policy_rejection发送策略拒绝了消息
domain_unverified发送域名未验证
quota_exceeded组织的发送配额已用尽
recipient_not_allowed该收件人不被允许用于此次发送;使用共享入门域名发送时,邮件只能送达工作区中已验证的成员
workspace_suspended工作区已暂停,因此这封邮件未发送,重新激活后也不会发送

Bird 会随时间增加拒绝原因,因此 Webhook 或收件人记录可能包含此表中尚未列出的原因。遇到不认识的原因时,将其视为原因未列出的拒绝,并保留该值以便日后查询。

当接收邮件系统在拒绝前可以被分类时,事件 API 还会额外提供 mailbox_provider 和 mailbox_provider_region。

email.complained

收件人将消息标记为垃圾邮件,邮箱提供商通过反馈环路将此信息回报。投诉在投递后到达,并将终态设为 complained。载荷:feedback_type(提供商发送的报告类型,例如 abuse 或 fraud,提供商未说明时为 null),以及来自事件 API 的 mailbox_provider 和 mailbox_provider_region。投诉会针对其归属的 Brand 阻止营销邮件;无法可靠确定 Brand 归属时,则在整个工作区范围内阻止。请保持低投诉率:提供商会限制积累大量投诉的发送者。

互动事件

email.opened

消息正文中的跟踪像素被加载。载荷:已知时包含 ip_address 和 user_agent;事件 API 额外提供 is_prefetched、country(ISO 3166-1 alpha-2,由客户端 IP 推导)、mailbox_provider 和 mailbox_provider_region。在计入打开数之前请检查 is_prefetched。 当收件箱隐私功能自动获取了像素而非真人打开邮件时,它为 true,计入这些会虚增你的打开率。打开和点击跟踪介绍了检测机制。

email.clicked

收件人点击了一个被跟踪的链接。载荷:url(被点击的链接)、ip_address,以及已知时的 user_agent;事件 API 额外提供 country、mailbox_provider 和 mailbox_provider_region。点击通常是比打开更强的互动信号,因为隐私代理可能自动加载跟踪像素。

email.unsubscribed

收件人使用了消息正文中的退订链接。载荷:webhook 上仅包含身份基础字段;事件 API 额外提供 mailbox_provider 和 mailbox_provider_region。记录退出偏好以阻止营销邮件。退订链接介绍了如何将链接添加到邮件中。

email.list_unsubscribed

收件人使用了邮箱提供商在其自身 UI 中呈现的一键退订按钮,该按钮由消息的 List-Unsubscribe 邮件头驱动。载荷:webhook 上仅包含身份基础字段(事件 API 额外提供 mailbox_provider 和 mailbox_provider_region);机制即事件类型本身,这也是它与 email.unsubscribed 分开的原因。同样记录退出偏好以阻止营销邮件。

消息级事件

有两种事件描述整条消息,而不是单个收件人。因此,其 data 包含 email_id、workspace_id、brand_id、tags 和 metadata,但不包含收件人身份。两者都属于定时发送。

email.scheduled

我们接受了一个 scheduled_at 设在未来的发送。载荷:消息级基础字段加 scheduled_at。到达该时间后,每收件人的生命周期从 email.accepted 开始。

email.canceled

定时消息在发出前被取消,因此不会产生任何收件人生命周期事件。载荷:仅包含消息级基础字段。

入站和邮箱事件

email.received 涵盖入站邮件。当我们收到并解析入站消息时触发。其载荷包含 inbound_message_id、地址信息、主题和认证判定。设置、载荷和回取 API 请参阅接收邮件。邮箱在此基础上拥有自己的 email_mailbox.* 系列事件,详见邮箱指南。

退信分类

bounce_class 是包含在 email.bounced、email.out_of_band_bounce 和 email.deferred 上的数值退信分类。它汇总为粗粒度的 bounce_type 并保留细粒度代码,因此即使两者都报告为 soft,你仍能区分邮箱已满和路由故障:

bounce_classbounce_type含义
1undetermined接收服务器的响应含义不明确
10, 30hard永久失败:地址无效或域名不存在
20 至 24, 40, 70, 100soft临时失败:邮箱已满、服务器暂时不可用、DNS 或路由问题
25admin管理性拒绝:中继被拒绝、域名被列入黑名单
50 至 54block接收服务器拒绝了发送 IP

不在此列表中的类别映射为 undetermined。只有 hard 退信会屏蔽该地址;soft、block、admin 和 undetermined 不会,因为该地址可能仍然可达。

自动屏蔽

硬退信会创建工作区范围的屏蔽。能可靠确定 Brand 归属的垃圾邮件投诉会为该 Brand 记录受保护的邮件偏好;无法可靠确定归属的投诉会创建工作区范围的屏蔽。

事件结果阻止的内容
email.bounced 或 email.out_of_band_bounce(bounce_type: "hard")屏蔽,reason: hard_bounce所有 Brand 的所有类别邮件
具有可靠 Brand 归属的 email.complained偏好,origin: complaint来自该 Brand 的非事务性邮件
没有可靠 Brand 归属的 email.complained屏蔽,reason: complaint所有 Brand 的非事务性邮件

email.complained 仍是消息级的投诉事件。如果某个 Brand 投诉将有效偏好变为已撤销,还会发出 preference.revoked,其中包含 preference_id 和 brand_id。重复投诉不一定会再次产生偏好变更。获取该偏好可查看其当前来源、状态和保留的 complaint_message_id。

同步收件人的选择时,请订阅 preference.revoked、preference.granted 和 preference.deleted,即使工作区只有一个 Brand。用它们刷新当前偏好及其渠道、联系方式、Brand、发送者和主题范围。偏好时间戳表示同意生效的时间,而非变更顺序;按时间戳排序无法还原当前状态或覆盖范围。请通过核对确认删除,并保留其他独立偏好和工作区屏蔽。

限定于 Brand 的投诉不会发出 email_suppression.created。该事件描述添加到工作区屏蔽列表的条目,包含 suppression_id、email、reason 和 workspace_id。移除屏蔽没有面向客户的 webhook,因此镜像还需要定期核对完整的分页列表。已有的工作区投诉屏蔽保持原有范围。请按照迁移指南中的同步方法操作,包括重试失败或滞后于变更的读取。

email.unsubscribed 和 email.list_unsubscribed 同样会记录偏好。退订链接介绍了它们的效果。屏蔽列表介绍了如何查看投诉保护,以及如何记录更新的个人选择加入。

后续向被屏蔽地址的发送会被立即拒绝,原因为 email.rejected(rejection_reason: "recipient_suppressed"),且不会计入你的可投递性指标。

后续步骤