简介

Bird API 是一个统一的 REST API，涵盖平台的所有功能。本参考文档记录了每个公开端点，由驱动官方 SDK 的同一份 OpenAPI 规范生成，因此这里的请求和响应结构与线上传输的内容完全一致。

参考文档侧边栏按产品分组最常用的资源：Email、SMS、WhatsApp、Apple Messages、Voice、eSIM、Realtime、Verify、Preferences、Numbers、Lookup、Workspace，以及开发者工具（Webhooks 和 Documentation，即文档搜索 API）。发送域名、入站邮件、联系人与受众拥有参考页面但没有侧边栏条目。你可以从创建发送域名、创建入站地址、创建联系人和创建受众开始，也可以从相应指南开始：发送域名、接收邮件、联系人和受众。Voice 部分包含通话、通话段日志、中继、号码、来电显示、目的地和 SIP 会话凭证。语音统计数据仍可通过控制面板和 CLI 查看。工作区设置、API 密钥和专用 IP 在控制面板中管理，而非通过公共 API。

资源页面通过指南中的深层链接关联：当指南提到某个端点时，链接会跳转到此处对应的参考条目。

面向编码代理

将代理指向以下机器可读资源：

• OpenAPI 规范：每个公开端点、模式和错误码，也提供 YAML 格式。SDK 由同一文件生成。
• API 索引：API 指南、所有操作参考和公开错误，按产品分组并链接到对应的 Markdown 页面。
• 文档索引：所有已发布的英文文档页面，按章节和产品分组。
• 站点索引：bird.com 上的产品、快速入门和代理工具。
• MCP server：托管在 mcp.bird.com 上的工具，通过浏览器登录后可操作你的工作区。
• Bird CLI：在终端中使用的 API。CLI for agents 介绍了其 JSON 输出和退出码。
• Markdown 页面：在任意文档 URL 后附加 .md（如 https://bird.com/docs/api.md），或发送 Accept: text/markdown。

产品地图

每张表格按顺序列出集成所需的调用，并附有各调用的参考页面链接和产品指南链接。

Email

SMS

Verify

其他产品

约定

所有端点遵循相同的约定。这些约定在此统一说明，不再在每个页面重复。

• 基础路径：所有端点位于区域主机（如 https://us1.platform.bird.com）上的 /v1 路径下。参见基础 URL 与区域。
• 身份验证：请求以 bearer token 的形式携带 API 密钥：Authorization: Bearer bk_us1_...。参见身份验证。
• JSON，snake_case：请求和响应体为 JSON 格式，字段名使用 snake_case（created_at、workspace_id），并且请求必须设置 Content-Type: application/json。
• 时间戳：所有时间戳均为 UTC 时区的 RFC 3339 字符串，字段名以 _at 结尾（created_at、delivered_at）。资源时间戳（如 created_at）由服务器分配且为只读。少数请求字段（如 scheduled_at）是由你提供的时间戳。
• 带类型前缀的资源 ID：每个 ID 都带有类型前缀：em_ 表示邮件消息，dom_ 表示发送域名，whk_ 表示 webhook 端点，sup_ 表示屏蔽记录，等等。前缀使 ID 在日志中具有自描述性，并防止将一个资源的 ID 误传给另一个资源。
• 部分更新使用 PATCH：PATCH 请求仅更改你包含的字段，省略的字段保持不变。少数通过 URL 中的名称寻址的子资源使用 PUT 写入，这会完整替换该子资源。
• 查询参数严格校验：如果请求携带了端点未记录的查询参数，将被拒绝并返回 422（E01029），而不是被忽略。请对照端点的参数列表检查拼写。
• 错误：每个错误响应使用相同的错误响应结构，包含用于粗粒度分支的 type、稳定的 code、人类可读的 message，以及联系支持时需要引用的 request_id。参见错误响应。
• 分页：列表端点使用基于游标的分页，共享相同的参数集。参见分页。
• 幂等性：变更类端点接受 Idempotency-Key 请求头，使重试安全可靠。参见 Idempotency-Key 请求头。
• 弃用：重命名的字段在旧名称下仍然有效，响应会通过 Deprecation 请求头告知此情况。参见弃用。

推荐客户端

你可以使用任何 HTTP 客户端调用 API，但官方客户端会为你处理身份验证、区域选择、重试和分页：

• 适用于 TypeScript、Go 和 Python 的官方 SDK：基于精选公开接口的类型化方法
• Bird CLI：在终端中使用的 API，同样适用于脚本和代理

在 Postman 中运行

整个 API 也是一个 Postman 集合，由同一份规范转换而来，每个端点都包含示例请求和响应。导入你所在区域的环境，将 apiKey 设置为工作区的 API 密钥，即可发送任意请求。

你也可以直接下载集合以及 us1 或 eu1 的环境。

延伸阅读

• 身份验证：请求在网络层如何进行身份验证
• 基础 URL 与区域：区域主机和区域模型
• 分页：游标、页面大小和排序
• Idempotency-Key 请求头：变更请求的安全重试
• 错误响应：错误响应结构和完整错误目录
• 弃用：被替代的字段名仍然有效，以及如何迁移