邮件 API 常见问题

发送到沙盒地址，如 delivered@messagebird.dev。结果取决于您使用的地址而非账户状态，因此您可以在验证域名之前测试发送、Webhooks 和抑制功能。bounce@ 和 complaint@ 等地址会通过我们的真实管道模拟相应结果。安装一个 SDK，大约五分钟即可发送到测试地址。

不需要立刻验证。拥有 API 密钥后，沙盒地址即可使用。要发送给真实收件人，则需要验证域名：添加我们提供的 DNS 记录即可。Free 计划可注册 1 个发送域名，Startup 计划 10 个，Growth 计划 1,000 个。

事务性和营销邮件发送、模板、支持 DKIM/SPF/DMARC 的发送域名、专用 IP 和 IP 池、退订管理、入站邮件、Webhooks 以及送达率分析——全部集成在一个 API 中。SDK 覆盖 TypeScript、Python、Go、PHP、Kotlin 和 Swift，文档与 REST API 保持一致的数据结构。此外还有 CLI 工具（通过 brew install messagebird/tap/bird 安装），以及托管 MCP 服务器，方便您接入智能代理而非传统应用。

Free 计划每月免费提供 1,000 封邮件，无需信用卡。付费计划起步价为 $15/50K 封，单价随发送量增加而递减。超出计划额度的部分按每 1,000 封计费，费率随层级提升而降低：Startup 和 Growth 底层为每 1,000 封 $0.90，月发送量达 250 万封时降至每 1,000 封 $0.50。企业协议可完全取消上限。

降级不会影响现有功能：您已经申请的地址前缀会继续工作，只是在回到配额范围内之前无法申请新的。使用您自己域名的邮箱与其他邮箱一样计入总邮箱配额，其本地部分不会占用自定义地址前缀的配额。

Growth 套餐中每个专用 IP 每月 $24.95，最多五个。无设置费，无年度承诺。

单发和批量发送分别限速，限制计算的是请求数而非收件人数——这正是批量发送成为扩容利器的原因。免费版密钥每分钟可发送 10 次单发请求和 5 次批量请求，付费计划会提高两项上限。不要硬编码这些数值：每个响应都会携带 IETF RateLimit 头，告知剩余配额和窗口重置时间，请据此调节发送速率，而非等到收到 429 错误。单次批量调用最多可发送 100 封邮件，每封邮件的收件人（to）、抄送（cc）和密送（bcc）各最多 50 个地址。

所有计划均为 20 MB，按生成后的邮件计算：包括 HTML、纯文本部分以及经过 base64 编码后的所有附件。请将原始附件控制在 15 MB 以内，以留出编码空间。收件方也有自己的大小限制，因此接近上限的邮件可能被我们接受后在对方端退回。我们保留邮件数据 30 天，如需更长时间保存，请通过分析 API 或 Webhooks 将数据导出到您自己的存储中。

通过限定权限的密钥、审计写入操作和分类感知的退订管理：营销邮件无法发送给已退订的收件人。入站洪流也会被遏制——被拦截的邮件不会触发任何 Webhooks。

可以，两者通过同一个发送 API 提交。唯一的区别是 category 字段，它决定了退订和取消订阅的适用规则。密码重置和收据选择 transactional，营销活动选择 marketing。

每次逻辑发送时附带一个 Idempotency-Key 请求头。如果第一次请求已成功但您未收到响应，使用相同的密钥重放请求会返回原始结果并附带 Idempotency-Replay 头，而不会重复发送邮件。

将 scheduled_at 设置为 30 秒到 30 天后的任意时间。发送请求会立即返回已接受状态，邮件保持计划状态直到发出，因此您可以在发送前随时取消。

可以，以 base64 编码放入 attachments 数组中。要在正文中内联显示图片，为其设置 content_id 并在 HTML 中通过 cid: 引用。原始文件大小请控制在 15 MB 以下，以确保编码后的邮件不超过 20 MB 上限，请注意可执行文件和脚本内容类型会在发送前被拒绝。

不需要。您可以完全通过 API 操作：将带有占位符的 HTML 直接内联编写并发布，然后在发送时通过 id 或 slug 引用该模板。我们会自动识别占位符，无需单独声明。React Email 同样适用：将组件渲染为 HTML 并将结果存储为正文，在 JSX 中保留每个占位符为字面文本，这样它在渲染后保留并在发送时填充。目前没有 AI 生成或拖拽式编辑器。

您通过 id 或 slug 引用模板，因此每次只需发送每个收件人的个性化值，而不是每次都传入完整正文，且布局集中在一处管理，而非在每次调用时由代码重新构建。模板支持版本管理，个性化在我们端渲染：条件判断、数组循环和字段默认值都按收件人解析，因此会员模块可以仅对会员显示。发送时使用普通的发送调用，将 template 设置为 id 或 slug，将个性化值放入 template.parameters。

可以。发布会冻结一个不可变的编号版本，编辑始终在草稿上进行，因此在您发布之前，线上内容不会发生任何变化。回滚到任何先前发布的版本，即可将其设为发送时使用的版本，且不会创建新版本。回滚还会将草稿重置为该版本的内容，后续编辑将从该版本开始。

全局的。联系人以邮箱地址为唯一标识，受众只是引用它，因此在受众之间移动联系人时其属性会自动跟随，因为属性存储在联系人上，而非列表上。自定义字段存储在属性注册表中，这是一个封闭的、有类型约束的架构，需要您预先定义：声明每个字段的类型（字符串、数字、布尔值或日期时间），可选设置默认值，写入时我们会拒绝未知键或类型错误的值，确保您的数据始终干净。

将 CSV 或 Excel 文件拖入仪表板，Bird 会自动识别各列对应的字段，每次最多支持 50,000 个联系人。或者通过 API 批量 upsert，单次调用最多 1,000 个，并在同一请求中将其加入受众，无需额外的添加步骤。无论哪种方式，upsert 都基于每条记录携带的标识符进行幂等操作，因此重复导入只会更新而不会产生重复数据。群发针对单个受众：在此处创建和维护受众，然后在发送时通过 ID 引用它。

将其指向单个受众。受众是唯一的定向概念，您无需在其上叠加列表和分群。

两者都可以。可以立即发送，也可以设置一个明确的时间戳进行定时发送，时间范围从 30 秒到 30 天。一旦已定时或正在发送中，您都可以取消：群发可以从任何非终态转为已取消状态。

是同一个。营销邮件和事务性邮件共享同一个 API、同一套密钥和同一个分析界面。群发功能在您已有的发送基础设施之上增加了营销活动生命周期管理。如何分离两者的发送信誉，由您自行决定。

每封邮件都经过 DKIM、SPF 和 DMARC 认证，IP 自动预热，退信和投诉会自动触发退订，确保同一个无效地址不会二次损害您的信誉。黑名单监控会在您还能采取行动时就标记问题。退订和投诉也会自动且可逆地抑制该收件人，内置一键 List-Unsubscribe，群发邮件在发送前会自动应用营销退订列表。

送达、打开、点击、退信和投诉，可按活动、标签和邮箱服务商细分，并过滤掉预取打开。控制台中的所有数据也可通过统计 API 获取。

我们会为您生成所需记录：一条 DKIM TXT 记录用于签名邮件，一条 return-path CNAME 记录用于对齐 SPF（无需顶级域 SPF 记录），以及一条 DMARC TXT 记录。用于品牌化打开和点击链接的跟踪 CNAME 是可选的。添加域名，将记录粘贴到您的 DNS 服务商处，然后点击验证：大多数验证在 DNS 传播后几分钟内即可完成，偶尔可能需要更长时间。

DMARC 告知接收服务器如何处理 DKIM 或 SPF 对齐失败的邮件，以及将显示谁在以您的域名发送邮件的聚合报告发送到哪里。我们要求在域名可以发送邮件之前必须设置 DMARC 记录，建议从 p=none 开始，即仅监控而不影响投递。一旦您确认所有合法来源都已对齐，再将策略收紧到 p=quarantine 或 p=reject。如果您的域名或父域名已发布了 DMARC，我们会直接使用。主要邮箱服务商现在要求批量发送者发布策略，因此拥有 DMARC 记录越来越成为大规模送达收件箱的必要条件。

两者都可以，我们推荐使用专用子域名，因为它可以将您的邮件信誉与企业邮件隔离开来。您还可以为事务性邮件和营销邮件分别使用不同域名，或每个品牌一个域名，各自拥有独立的身份验证和信誉。

当您的发送量持续较高时——大约每月 100,000 封或以上。低于此量级，共享 IP 池的送达率更好，因为信誉是共享的，专用 IP 只有在发送量足够大以保持其活跃时才有帮助。您无需自己预热：我们会在大约 30 天内自动预热新的专用 IP，逐步提升发送量，让邮箱服务商逐渐建立信任，同时溢出流量走共享池，确保您的发送量不会下降。

可以。将 IP 分组到不同的 IP 池中，并将每种流量类型路由到各自的池中，这样营销邮件就不会影响承载密码重置等重要邮件的发送信誉。

送达率是指您的邮件是否真正到达收件人的收件箱，而非垃圾邮件文件夹或被硬拒绝。它取决于身份验证、发送者信誉、列表清洁度和互动情况，我们会为您管理或展示每一项。

我们会为您监控主要的黑名单。统计 API 和仪表板还会展示退回代码、投诉类型和邮箱服务商细分，帮助您及早发现下降趋势。

硬退回、垃圾邮件投诉或退订会将该地址加入您的抑制列表，之后您发送的任何邮件都不会再投递到该地址。这可以防止一个问题地址在后续每次发送中损害您的信誉。抑制并非永久性的：一旦您确认该地址已恢复，可以手动将其从列表中移除。

硬退信、垃圾邮件投诉和退订会被自动屏蔽：一旦收件人触发了其中之一，我们会将其加入您的屏蔽列表，并在后续发送中跳过。硬退信和您手动屏蔽的地址会阻止所有发送，但投诉和退订仅适用于营销邮件，因此密码重置等事务性邮件仍然能送达那些退出了您营销活动的用户。

三者都可以。屏蔽是可逆的，因此如果某个地址恢复正常，通过仪表板或 API 将其从列表中移除即可恢复发送。您也可以自行添加地址，例如导入一个已知无效的列表，它们会像自动添加的条目一样被跳过。要在不消耗真实地址的情况下测试该行为，可以向沙盒地址 suppressed@messagebird.dev 发送：它的行为与收件人被屏蔽完全一致，以 recipient_suppressed 被拒绝，但不会写入您的列表，因此可以反复使用。

我们跟踪送达、打开、点击、退回、投诉和退订等指标，以 KPI 形式汇总，并按域名、ISP、IP、发送域、收件人域、标签和群发进行细分，同时提供退回代码和投诉类型的详细信息。邮箱服务商和客户端细分还可以展示 Gmail、Yahoo、Outlook、Apple Mail 等是如何递送、打开和退回您的邮件的。

可以。仪表板上展示的所有数据都可以通过统计 API 获取，支持按天或按小时的粒度，因此您可以回填报告或将指标流式传输到自己的工具中。互动和递送事件也通过 Webhooks 近乎实时地到达，并汇总到统计端点中，因此仪表板和查询反映的是刚刚发生的情况，而非昨天的数据。

它是一个您的代码拥有的真实、可寻址的收件箱。发送到该地址的邮件会以对话线程的形式呈现，您的代理可以通过 API 读取、过滤、回复和发送，无需运行 IMAP 服务器或解析原始 MIME。普通的入站解析只提供原始邮件。代理邮箱增加了会话层：专属地址、带标签的对话线程、去除引用的纯文本，以及自动归入线程的回复。

可以。邮箱可以建在共享的 inbox.ai 域名上，也可以建在您自己的域名上（需配置入站转发）。任何不在 30 天删除隔离期内的本地部分均可使用。自动生成的地址由 20 个随机字符组成，始终可用且免费。自定义地址由您自行选择（如 goldcrest@inbox.ai），在所有组织中先到先得，并从您的计划配额中扣除。

如果您只需要将邮件解析为 Webhook，普通的入站邮件就足够了。当代理需要维持一段对话时，邮箱才真正发挥价值。开始使用只需几分钟：在控制台创建 API 密钥、认领一个地址、回复您的第一个对话线程。文档涵盖了完整流程，托管 MCP 服务器则让代理无需编写任何 HTTP 代码即可使用相同的工具。

两者都是本地部署的 MTA，由您自行运行，而非通过我们的托管 API 发送。Momentum MTA 围绕可自定义的工作流和路由构建，适用于大批量发送。PowerMTA 则设计为在您自己的服务器或任何公有云（如 AWS 或 Azure）上运行。

适用于因基础设施或合规要求需要自行运行 MTA 的团队，以及希望独立了解收件箱送达和竞争对标情况、而不仅仅依赖自身发送指标的团队。第一类团队运行 Momentum MTA 或 PowerMTA。第二类团队使用 Inbox Tracker（基于真实邮箱数据衡量收件箱送达和信誉）或 Competitive Tracker（将您的邮件项目与其他品牌进行对标），这两者都不需要您自行托管任何内容。

SparkPost 现在是 Bird Email。我们于 2021 年收购了 SparkPost，将其背后支撑全球约 40% 商业邮件的投递引擎整合到一个涵盖邮件、SMS、WhatsApp 和语音的统一平台中。现有 SparkPost 客户保留其服务，无需迁移。新项目使用 Bird Email API 构建，它运行在同一个投递引擎上，并在一套密钥下增加了 SMS、WhatsApp 和语音功能。

投递引擎与 SparkPost 运行的是同一个，但接口是现代化的邮件 API，提供所有主流运行时的 SDK。其文档涵盖发送、模板、发送域名和 Webhook。

Momentum 是我们面向大批量发送的本地部署邮件基础设施平台，通过其 Policy Manager 提供可自定义的工作流、路由和投递参数。它能随发送量扩展并保持稳定性能，且支持完整 Unicode（SMTPUTF8），可发送至国际字符集地址。

Adaptive Delivery 是 Momentum 的自动流量整形功能。它监测每个邮箱服务商对您邮件的响应，并实时调整：限流、延迟或短暂暂停某条发送流以保护您的信誉，待情况好转后再恢复发送速率。您无需为每个服务商手动调控发送速率即可达到收件箱。Intelligence Router 可跨所有数据源展示这些调整过程，并在每次调整时发出实时警报。

两者皆是。Momentum 可运行在您自己的服务器、任何主流云平台，或混合部署，以匹配您的基础设施、成本和合规需求，并可随时调整配比。它也在持续更新：近期版本保持对现代操作系统、TLS 1.3 以及最新安全和 SMTP 标准的支持，并通过实时 API 暴露消息事件，供您接入自有报告和自动化系统。

可以。PowerMTA 可以将部分流量中继到托管的 Bird Email API，其余流量直接从您自己的服务器发送——这是试用托管平台或逐步迁移最简单的方式，无需一次性全部迁移。PowerMTA 本身运行在您自有的基础设施上，这些 IP 由您自行管理。中继到托管平台的流量可以使用我们的 IP，也可以使用您的专用 IP，其他一切完全由您掌控。

虚拟 MTA 让您在单个 PowerMTA 实例中运行多条独立的发送流，每条拥有独立的 IP、信誉和限制。用它来将事务性邮件和营销邮件，或不同客户的邮件彻底分开，确保一条流的问题不会影响其他流。

送达率是指您的邮件是否到达收件箱，而非垃圾邮件文件夹或被拒收。Inbox Tracker 按邮箱服务商实时监测，并提供每日明细，展示您的邮件实际落入了哪里：收件箱、垃圾邮件还是被拦截。

Inbox Tracker 会在某个邮箱服务商的投放率下降时立即发出警报，让您在每日明细中就能发现问题，而不是等到几周后回复率下降才察觉。它还会标记垃圾邮件陷阱命中情况——这通常意味着列表质量问题，应在损害您的信誉之前及时修复——并在 DMARC 认证开始失败时向您发出提醒。

三个数据源：授权邮箱数据，显示您的邮件在真实收件人那里的实际投放情况；种子账户，用于在特定场景中测试投放效果；以及直连 Google Postmaster，获取 Gmail 对您信誉的评价。它们各自回答不同的问题——真实邮箱数据告诉您结果，Postmaster 告诉您 Gmail 的判断逻辑，种子账户则让您主动测试特定场景。单一数据源会存在盲区并产生误报。

我们每天跟踪来自超过 100 个行业、250,000 多个品牌的数百万封邮件。数据持续刷新，因此您看到的洞察反映的是当前的营销活动和趋势，而非历史快照。

您可以将受众规模、活动频率、消息策略、绩效指标和互动率与行业内其他品牌进行对比，细化到单个竞争对手的邮件旅程。同样的视图也适用于季节性规划：观察竞争对手如何在季节到来前调整其营销活动，并在您做出决策前了解哪些策略正在奏效。

通常可以。Competitive Tracker 能够识别竞争对手邮件背后的发送平台或服务，这对竞争研究以及销售团队了解潜在客户的竞争对手如何运营其邮件项目非常有用。

服务商会将此视为地址采集行为，并对您进行速率限制或列入黑名单，而且结果并不可靠：服务器可能在握手阶段接受了某个地址，但实际上仍然无法投递，灰名单机制还会让真实地址看起来无效。通过投递历史进行验证可以同时避免风险和错误结果。

对于 Neutral 结果，由您自行判断：该地址格式正确，有真实的邮件服务器，且从未发生过硬退信，但我们尚未观察到该地址的投递或互动事件，因此风险较低而非可疑。如果您注重增长，可以直接发送；如果您更倾向于稳妥，可以等到观察到互动后再发送。对于 Typo 结果，在注册表单中展示建议的更正，让用户在提交前修正，这样可以挽回一个原本会退信的线索；在批量列表中，将拼写错误的地址分离出来进行确认或删除，但不要向拼写错误的地址发送邮件。

是的。API 仅支持 HTTPS。如果您改用 SMTP 提交，端口 465 从第一个字节起即加密，端口 587 和 2525 通过 STARTTLS 升级加密：在升级完成前我们拒绝 AUTH，因此凭据永远不会以明文传输。端口 25 不提供邮件提交功能。您的数据存储在您组织所在的区域，us1 或 eu1，您的 API 密钥前缀（bk_us1_…、bk_eu1_…）编码了该区域信息，因此 SDK 和 CLI 会自动选择正确的端点。只有身份验证和账户管理运行在与区域无关的主机上。

只能执行您授予的权限范围。密钥携带一组作用域列表，如 emails、email_marketing 或 domains，每个作用域分为读取或写入权限，因此用于发送邮件的密钥无法管理您的发送域名。控制面操作（成员管理、工作区设置、密钥签发、IP 池）仅限仪表板操作，任何密钥都无法访问。每个密钥还支持 CIDR 范围白名单，来自其他地址的请求会被拒绝。

轮换操作会签发新密钥，同时旧密钥在宽限期内继续有效（默认 24 小时），以便您在部署中逐步替换。传入零可立即撤销旧密钥。轮换不会延长密钥的有效期：如果密钥的到期时间早于宽限期，则保持原有的到期时间。

可以，支持 SAML 2.0 或 OIDC，因此 Okta、Microsoft Entra ID 和 Google Workspace 都可以使用。配置按组织进行：您的客户团队会为您开通。使用密码登录的成员可以自行开启 MFA。

是的。审计日志是只读的、组织范围的管理操作记录，包含操作者、工作区、时间和结果，并支持导出为 OCSF 格式以接入您自己的 SIEM。它记录的是配置变更，而非您发送的邮件内容。邮件内容记录在邮件日志中。

认证和安全文档发布在信任中心 trust.bird.com。数据处理协议、隐私声明和可接受使用政策发布在 bird.com/legal，包含当前版本以及已替代版本的存档。如需供应商调查问卷，您的客户团队会负责处理。