简介

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

参考文档侧边栏按产品分组最常用的资源：Email、SMS、Voice、Realtime、Verify，以及开发者工具（Webhooks 和 Documentation，即文档搜索 API）。其他公共端点（包括发送域名、入站邮件、联系人与受众，以及 WhatsApp）可通过搜索和相应指南中的深层链接访问。Voice 部分包含通话、通话段日志、中继、号码、来电显示、目的地和 SIP 会话凭证。语音统计数据仍可通过控制面板和 CLI 查看。工作区设置、API 密钥和专用 IP 在控制面板中管理，而非通过公共 API。

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

约定

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

基础路径：所有端点位于区域主机（如 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 请求头告知此情况。参见弃用。

在 Postman 中运行

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

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

简介

约定

推荐客户端

在 Postman 中运行

延伸阅读

相关资源