API 概览

通过 Warmbly API，你可以以编程方式完成控制台中的所有操作，包括管理邮箱、营销活动、联系人、统一收件箱等。这是一套通过 HTTPS 提供的 JSON API。

https://api.warmbly.com/v1

快速入门

在控制台的“设置”中创建 API 密钥，然后在每次请求中将其作为 Bearer 令牌传入：

curl -X GET "https://api.warmbly.com/v1/campaigns" \
  -H "Authorization: Bearer wmbly_your_api_key_here" \
  -H "Content-Type: application/json"

有关密钥格式、权限范围和安全建议，请参阅身份验证。

版本管理

API 的版本号包含在 URL 中。当前版本为 v1，基础 URL 中也包含该版本号：本文档中的所有端点路径均相对于 https://api.warmbly.com/v1。

• 稳定性：同一版本内的变更均为增量更新，例如新增字段或端点。破坏兼容性的变更会以新版本发布，因此面向 v1 编写的代码可以继续运行。
• 版本请求头：每个响应均包含 API-Version 响应头，便于确认实际响应请求的版本。
• 不提供无版本号的别名：所有端点均位于 /v1 下，不提供省略版本号的路径。未来的破坏性变更将以 /v2 发布，同时 /v1 继续可用。

约定

• 权限：每个密钥都具有明确的权限集；超出密钥权限的请求会返回 403。完整列表见权限参考。
• 列表响应：列表端点采用一致的 data 与 pagination 响应结构，并使用不透明游标。
• 错误：错误响应除便于阅读的说明文字外，还包含供程序识别的 code 和 request_id。客户端应始终根据 code 与 HTTP 状态码判断后续逻辑，不应依据消息文本。请参阅错误码。
• 端点覆盖范围：端点权限范围对照表列出了所有路由、各路由是否接受 API 密钥，以及所需权限。端点参考按资源分类，说明每条路由的请求和响应结构。

{
  "data": [],
  "pagination": { "has_more": false, "next_cursor": null }
}

客户端库

Warmbly 提供适用于 JavaScript 和 TypeScript、Python 及 Go 的官方强类型 SDK。它们封装了 REST API、OAuth2 流程和实时网关，内置自动分页、重试及具有明确类型的错误。你也可以使用任意 HTTP 客户端直接调用 API。

安装命令和快速入门示例见 SDK。