Sign inGet started

发送域名

在我们能从您的域名发送邮件之前,您需要证明对该域名的所有权,并发布让邮箱提供商验证您邮件的 DNS 记录。发送域名是工作区级别的资源 (dom_...),用于跟踪该配置:需要发布哪些记录、哪些已通过验证,以及域名是否已准备好发送。

跨组织共享域名

同一域名可以被多个组织注册,互不影响。每个组织使用自己的 DKIM 密钥证明所有权,因此:
  • 同一域名上的其他组织永远无法查看您的验证状态或更改您的配置。
  • 每个区域(us1eu1)是独立的:同一域名在两个区域中是两个独立的注册,拥有各自的 DNS 记录。请在每个发送区域分别注册。

注册域名

使用 POST /v1/email/domains 创建域名。该调用作用于工作区级别,接收发送域名以及可选的 return-path 和 tracking 主机名标签。只需传入标签(sendlinks),我们会在您的发送域名下拼接完整主机名。省略的值默认为 sendlinks
请使用专用子域名(mail.acme.com)而非您的注册域名。这样可以将发送信誉与域名上的其他用途隔离,并且让我们要求您发布的所有记录远离区域顶点。第二个原因才是真正的隐患:用于接收的 MX 记录与已承载贵公司邮件的 MX 记录同名,因此在顶点发送域名上发布该记录会将那些邮件重新路由到我们这里。
const domain = await bird.domains.create({ domain: "mail.acme.com" });
console.log(domain.id, domain.status); // "dom_…", "pending"
响应包含 status: pending、分配给您组织的 DKIM 选择器,以及需要发布的 dns_records。已存在的工作区注册返回 409。超出组织的域名配额返回 422。对于 US 工作区,将 eu1 替换为 us1。API 密钥使用相同的区域前缀:bk_eu1_...bk_us1_...。您也可以在 Email > Domains 中管理域名。
仪表板中的 Domains 页面,显示一个已验证的发送域名及其发送、return-path 和 tracking 功能

发布 DNS 记录

dns_records 数组为每条记录提供可直接复制粘贴的 namehostvalue。部分提供商会拒绝将过长的 DKIM TXT 值作为单个字符串;DNS 记录拆分工具可将其拆分为这些提供商所需的带引号字符串。需要发布的记录:
记录类型发送必需作用
DKIMTXT证明所有权并使用您组织的密钥对邮件签名
Return-path CNAMECNAME将退信路由回我们并覆盖 SPF;SPF 查找会跟随 CNAME,因此无需在域名顶点添加 SPF 记录
DMARCTXT覆盖发送域名的任何有效 v=DMARC1 策略,可设置在域名本身或其注册(组织)域名上。一个最小化的 p=none 策略即可。
Tracking CNAMECNAME启用品牌化的打开/点击跟踪主机名;验证通过后,跟踪链接将通过 HTTPS 提供
Inbound MXMX将域名的邮件路由到我们以便接收。在您启用接收之前带有 optional: true;发布后将替换域名当前使用的 MX 记录。
有关每条记录的用途和值,请参阅 DKIM、SPF 和 DMARC。接收 MX 记录位于 dns_records 中并带有 purpose: inbound_mx(前提是接收功能在您的区域可用),在您对域名启用接收之前它们带有 optional: true。跳过所有标记为 optional 的记录,除非您需要其启用的功能。有关 DNS 提供商的配置步骤,请参阅 CloudflareRoute 53通用注册商指南。
仪表板会根据域名的 nameserver 检测受支持的 DNS 提供商,并链接到其 DNS 设置。打开 Email > Domains,然后选择域名查看其记录。如果由其他人管理您的 DNS,POST /v1/email/domains/{domain_id}/dns-records/share 会将需要发布的记录通过邮件发送给他们。
仪表板中域名的 DNS Records 页面,显示已验证的 DKIM 记录及可复制的名称和值,后面是 return-path 和 DMARC 部分

验证生命周期

新域名的初始状态为 pending。您无需轮询,因为我们会自动检查您的记录。检查从注册后立即开始,在前三天内从每几分钟逐步降低到每小时一次,之后对所有活跃域名每天检查一次。发布记录后等待即可;大多数域名在 DNS 传播后几分钟内即可通过验证。如果您想立即检查(例如刚修改完 DNS 后),请调用 POST /v1/email/domains/{domain_id}/verify:它会执行一次最新检查并返回更新后的域名。返回 200 且记录仍为 pending 并非失败;这意味着记录尚未被找到,在 DNS 传播期间(几分钟到几小时)这是正常的。该调用可在等待期间安全地重复执行。
保持未验证状态约 14 天的域名将被移除。我们会在移除前几天向工作区发送提醒邮件,以便您完成配置。
域名的顶层 status 反映所有权,由 DKIM 记录证明:
  • pending:DKIM 记录尚未发布。
  • verified:DKIM 记录已就位;所有权已确认。
  • failed:DKIM 记录存在但与预期值不匹配,或先前已验证的记录被移除。请修正记录以恢复。
  • temporary_failure:DNS 解析暂时失败;验证将自动重试。
  • rejected:域名因策略原因被拒绝;请联系支持。
发送就绪状态在 capabilities 下单独报告。发送门控为 capabilities.sending,只有当 DKIM、return-path CNAME 和 DMARC 策略全部就位时才会验证通过;域名顶点的 SPF 不是必需的。跟踪就绪状态(capabilities.tracking)独立于发送门控:它控制是否可以使用品牌化的打开/点击跟踪,不影响域名是否可以发送。

已验证记录失效时

验证永不停止:每日复检确保已验证域名的记录持续有效,因此如果您的 DNS 后来出现问题,我们会发现。为避免瞬时 DNS 故障导致状态反复切换,开始复检失败的已验证记录会在警告状态下保持已验证并改为每小时复检,同时我们会通知您。只有在记录持续失败满 24 小时后,域名才会被降级;该时间窗口内任何一次通过的检查都会清除警告。降级在下次发送时生效,降级的域名在记录修复后会在下一次自动检查或手动验证时自动重新验证。

管理域名

区域。 域名状态按区域划分。如果您从 us1eu1 两个区域发送邮件,请在每个区域分别注册该域名;每个注册会获得自己的 DKIM 选择器,并独立完成验证。
更改 return-path 或 tracking 主机名。 这些主机名属于您工作区的域名配置。已验证的主机名永远不会被未验证的主机名替换:更改会先暂存,与您当前的活跃配置并行验证,只有在新记录通过检查后才会提升生效。
打开/点击跟踪。 settings 开关属于工作区的域名配置。开关更改仅适用于此域名配置。配置了跟踪域名后即可开启。在未配置跟踪域名的情况下启用会返回 409。开关仅在跟踪域名验证通过后才影响发送,因此验证是按每次发送强制执行的。
删除。 DELETE /v1/email/domains/{domain_id} 将发送域名从您的工作区中移除。该域名的其他用途不受影响。

后续步骤