Sign inGet Started

从其他服务商迁移

使用本指南将生产邮件从其他服务商迁移过来。映射发送请求、发布 DNS 记录、导入屏蔽列表、转换 Webhook 事件,并在将生产流量导向 Bird 之前测试集成。

迁移清单:

  1. 映射你的发送调用到 POST /v1/email/messages
  2. 重新指向发送域名和 DNS
  3. 导入屏蔽列表
  4. 将 Webhook 切换到我们的事件词汇
  5. 在正式切换前在邮件沙箱中验证

步骤 1、3 和 4 取决于你正在离开的服务商。你的服务商指南包含逐字段的载荷映射、屏蔽列表的导出位置以及 Webhook 事件名称对照表。

1. 映射发送调用

我们有一个单次发送端点 POST /v1/email/messages。你构建一个扁平的 JSON 载荷(无 personalizations 包装,无 MIME 组装),包含 from、to/cc/bcc 数组、subject、html 和/或 text、可选的 reply_to 列表,以及用于自定义邮件头的 headers。成功发送返回 202 Accepted,附带以 em_ 为前缀的消息 ID。投递结果通过 Webhook 和读取端点异步到达。完整载荷(包含每个字段的上限和默认值)见发送邮件。从你当前载荷的逐字段映射见你的服务商指南。如果你的应用当前通过 SMTP 提交,可能完全不需要迁移调用:我们接受 SMTP 提交到同一管道,这一步只需更换凭证即可。

使用 tags 作为消息列表、分析和仪表盘汇总中的筛选维度。使用 metadata 存储结构化上下文,Bird 会将其保存在消息上,并在 API 读取时返回。Webhook 事件也可以携带此上下文,但退订事件可能返回空值。限制详情见 Tags vs metadata。

在迁移代码之前,注意以下差异:

  • 定时发送、存储模板和附件均可迁移。 使用 scheduled_at 进行定时发送。使用 template 代替内联内容来引用存储模板。将文件映射到 attachments 数组。
  • 被屏蔽的收件人会被显式拒绝。 被屏蔽的地址仍会获得一个 recipient_id,并出现在消息的收件人列表中,状态为 rejected,附带一个 email.rejected 事件(rejection_reason: recipient_suppressed),不会被静默丢弃。即使所有收件人都被屏蔽,请求仍会以 202 被接受,每个收件人都会返回拒绝状态。详见屏蔽列表。
  • 为事务性邮件设置 category: "transactional"。 发送默认使用 marketing,类别控制屏蔽策略:marketing 会因投诉和退订而阻止发送,transactional 则会绕过它们继续投递。新闻通讯和营销活动使用默认值即可正确处理。将收据、密码重置和类似的事务性邮件标记为 transactional,以免被退订所拦截。

2. 重新指向域名和 DNS

使用 POST /v1/email/domains 或在 Email > Domains 中注册每个发送域名,然后发布 dns_records 中的记录。DKIM、return-path CNAME 和 DMARC 策略是发送的前置条件。已有的 DMARC 记录(包括父域上的)也满足要求。跟踪 CNAME 仅用于品牌化的打开和点击跟踪。发送域名涵盖了记录、验证生命周期和区域模型。如果你的 DNS 提供商要求拆分 DKIM 值,使用 DNS 记录拆分工具;如果需要策略,使用 DMARC 策略生成器。

大多数服务商要求你首先添加的一条记录在这里被有意省略了:你不需要在域名顶点发布 SPF 记录。SPF 针对 envelope-from 域名进行验证,而 return-path CNAME 已将其指向我们,因此 SPF 无需修改你的顶点即可通过并对齐。如果你的旧服务商曾让你在顶点 SPF 记录中添加 include:,请在过渡期间保留它,切换完成后再移除。它既不会帮助也不会影响通过我们发送的邮件,移除后可释放顶点 SPF 允许的 10 次 DNS 查找中的一次。完整说明见 DKIM、SPF 和 DMARC。

你可以在旧服务商的记录仍然生效时发布我们的记录。DKIM 记录使用我们的选择器。return-path 和跟踪 CNAME 是你选择的新主机名,你现有的 DMARC 记录无需修改即可满足要求。两个服务商可以同时进行身份验证,直到你准备好切换流量。域名状态是按区域的,因此需要在你发送邮件的每个区域注册域名。

3. 导入屏蔽列表

在通过我们发送生产流量之前迁移你的屏蔽列表。否则,你的首批发送会到达那些在旧服务商已经产生退信或投诉的地址,从而损害你正试图保护的信誉。

从当前服务商导出列表(你的服务商指南中有具体的端点),然后使用 POST /v1/email/suppressions 将每个地址添加到这里:

代码示例
while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

关于此导入方式需要了解两点:

  • 每次请求只能导入一个地址。 屏蔽列表 API 是单条目 CRUD,因此导入大型列表需要循环遍历导出的地址。该调用是幂等的(新记录返回 201;如果地址已通过手动方式被屏蔽,则返回 200 及现有记录),因此可以安全地重新执行未完成的导入。
  • 导入的地址会获得 reason: manual、applies_to: all,这会阻止所有类别的发送,包括事务性邮件。这比原生投诉记录更严格,后者仅阻止非事务性发送。如果你需要针对特定地址使用按类别区分的行为,请参阅屏蔽列表中的原因分类。

今后,无论是否能归属到 Brand,硬退信都会创建工作区屏蔽并触发 email_suppression.created。无法可靠归属到 Brand 的投诉也会创建工作区屏蔽并触发 email_suppression.created。可归属到 Brand 的投诉会记录为受保护的偏好设置。退订会记录为偏好设置。即使工作区只有一个 Brand,也请同时订阅偏好事件,以便你的系统同步这些退订以及之后的重新授权。消息级的 email.complained、email.unsubscribed 和 email.list_unsubscribed 事件仍然可用。两者的区别见邮件事件。

4. 切换 Webhook

使用 POST /v1/webhooks 注册一个端点,并为其订阅明确的事件类型列表。我们的事件名称遵循 resource.action:正常路径为 email.accepted → email.processed → email.delivered,其余由 email.deferred、email.bounced、email.complained、email.rejected、email.opened、email.clicked 及退订事件对覆盖。从你当前服务商词汇的事件名称对照见你的服务商指南。每个事件的载荷结构见事件参考。

使用 email_id 和 workspace_id 关联出站消息事件;收件人生命周期事件还包含 recipient_id。请在发送时保存消息与客户的对应关系。tags 和 metadata 存在时仅作为补充上下文:对于单次发送,来自 Bird 退订链接的 email.unsubscribed 和 email.list_unsubscribed 会返回空值,即使发送时包含了它们。当上下文不可用时,群发退订事件也可能返回空值。

将 preference.revoked、preference.granted 和 preference.deleted 作为刷新偏好同步副本的信号。这些事件标识 preference_id 和 transition_id,并包含渠道、地址、Brand、发件人和主题作用范围;它们不包含消息 ID 或发送元数据。其 timestamp 是该声明的生效时间,而不是记录版本。延迟到达的投诉可能撤销之后的批量授权,不同的变更也可能具有相同的时间戳。不要通过对事件排序或将 transition_id 当作顺序序列来确定当前状态或覆盖范围。

按以下顺序初始化并维护完整的偏好设置同步副本:

  1. 订阅偏好事件,并在开始初始读取之前持久保存收到的通知。
  2. 读取工作区偏好设置列表的所有分页来初始化同步副本,不使用渠道、地址或 Brand 筛选条件。这样可以发现从未向你的端点发送过通知的现有退订。保留每条记录的 ID、渠道、地址、Brand、发件人和主题作用范围。
  3. 处理已保存的通知和新通知时,获取当前偏好设置,并读取受影响渠道和地址的所有分页。比较作用范围,以识别删除后以不同 ID 重新创建的情况。同时定期核对完整的、未经筛选的工作区列表,包括未出现在通知或本地同步副本中的收件人。

读取结果可能滞后于变更:遇到临时错误或意外缺失、较旧的状态时请重试。读取失败或不完整时,不得清除本地的阻止状态。只有确认记录已不存在后才移除已删除的记录;保留其他独立的偏好设置和屏蔽记录。此同步副本会随时间趋于一致,但不能取代 Bird 在发送时的检查。

email_suppression.created 通过 suppression_id、workspace_id 和 email 标识新增的屏蔽。没有面向客户的屏蔽删除事件。要发现在仪表盘或通过 API 进行的移除,请定期读取工作区屏蔽列表的所有分页,并按屏蔽 ID 核对。扫描失败或不完整后不要移除记录;在后续读取中确认记录缺失后再移除。将屏蔽记录与偏好设置分开存储,这样移除一项阻止不会清除另一项。

我们按照 Standard Webhooks 规范对投递进行签名,使用三个请求头:webhook-id、webhook-timestamp 和 webhook-signature,通过对 {id}.{timestamp}.{raw body} 做 HMAC-SHA256 计算。如果你已经在其他平台验证过 Standard Webhooks 投递,完全相同的验证代码在这里同样适用。否则,验证方法、重试计划和重放工具见 Webhooks 与事件。投递是至少一次且无序的,因此需要基于 webhook-id 去重。使用消息事件的时间戳展示消息的时间顺序;对于偏好设置和屏蔽列表,按上文所述基于当前状态进行核对。

5. 切换前在沙箱中验证

在迁移生产流量之前,在邮件沙箱中测试迁移后的发送调用和消息事件处理程序。沙箱发送使用 messagebird.dev 的魔法地址,并通过真实生产管道处理:相同的 202、相同的事件序列、相同的签名 Webhook 投递,但不会到达任何收件箱或影响你的信誉。

沙箱信号不会写入屏蔽记录或投诉偏好记录。使用Webhook 事件契约中具有代表性的 email_suppression.created、preference.revoked、preference.granted 和 preference.deleted 载荷,单独测试你的同步副本,包括两个 Brand 共享同一收件人的情况。请包含以下场景:

  • 某条未发生变化的退订早于 Webhook 注册。初始的未筛选清点无需通知即可发现它;定期清点也能发现本地同步副本中缺失的记录。
  • 单次发送的退订事件中 tags 和 metadata 为空值;你保存的消息对应关系仍能识别客户。
  • 投诉在较新的批量授权之后到达,或者较早的全类别退订扩大了投诉保护范围,但未推进其生效时间戳。以相反顺序投递这些事件,并验证核对后仍保留当前的已撤销状态和覆盖范围。
  • 某个偏好设置被删除后重新创建,或者在仪表盘中移除了手动屏蔽。核对只移除已确认不存在的记录,并保留无关的阻止状态。
  • 刷新失败或暂时返回较旧的状态。你的处理程序会重试,定期核对会修复同步副本,且不会因读取失败而清除阻止状态。

最小化的切换前冒烟测试:

  1. 发送到 delivered@messagebird.dev,断言你的处理程序处理了 email.accepted → email.processed → email.delivered。
  2. 发送到 bounce@messagebird.dev,断言你的退信处理在 email.bounced 上触发(模拟退信不会写入你的屏蔽列表,因此该地址可以继续使用)。
  3. 发送到 suppressed@messagebird.dev,断言你处理了 email.accepted 后跟 email.rejected,之后没有 email.processed 或投递事件。这就是生产环境中每个被屏蔽收件人产生的事件形态;rejection_reason: recipient_suppressed 详情在收件人记录和事件的 API 中。
  4. 发送一条 category: "marketing" 消息,确认类别在消息读取中按预期显示。

使用 +label 子地址(bounce+cutover-test@messagebird.dev)来关联测试用例。完整地址会出现在你的事件中。冒烟测试通过后,切换流量。将你的应用指向我们,并保留旧服务商的 DNS,直到你的域名在这里显示为 capabilities.sending 已验证。在仪表盘和 Webhook 流中监控正式投递的最初几个小时。

从特定服务商迁移

  • SparkPost:transmissions 和 SMTP、模板转换、按作用范围区分的屏蔽列表和 Webhook 事件
  • SendGrid:personalizations → 扁平载荷,categories/custom_args → tags/metadata,dropped ↔ email.rejected 的等价关系
  • Mailgun:o:*/v:*/h:* 参数 → 一级字段,导出退信/投诉/退订列表
  • Amazon SES:SendEmail v2 → 单一端点,配置集 → 按消息的跟踪标志,SNS → 签名 Webhook
  • Resend(服务商名称,并非“重新发送”):载荷结构几乎相同,Svix 签名的 Webhook → Standard Webhooks
  • Postmark:逗号分隔的收件人 → 数组,按流的屏蔽列表导出,无签名 Webhook → 签名 Webhook
  • Brevo:地址对象 → 纯地址,两个独立的阻止列表需导出,params → template.parameters
  • MailerSend:五个屏蔽列表(其中临时列表无需迁移),personalization → 按发送参数
  • Mailjet:Messages 数组 → 单一扁平载荷,EventPayload → metadata,阻止列表导出
  • Mandrill:message 包装和请求体认证 → 扁平载荷和 bearer 认证,导出拒绝黑名单

后续步骤