SDK
面向 JavaScript、Python 和 Go 的 Warmbly 官方客户端库。
Warmbly 提供适用于 JavaScript 和 TypeScript、Python 及 Go 的官方 SDK，均具有完整类型支持。每个 SDK 都封装同一组接口：REST API、OAuth2 授权流程和实时网关。它们提供强类型资源、自动分页、自动重试和实时事件流，无需手动编写 HTTP 调用。三个 SDK 均为开源项目，并与 v1 API 保持同步。
官方客户端库
| 语言 | 软件包 | 运行环境 | 实时服务 |
|---|---|---|---|
| JavaScript 和 TypeScript | warmbly（npm） | Node 20+、Bun、Deno、浏览器、边缘运行环境 | 是 |
| Python | warmbly（PyPI） | Python 3.10+，支持同步和异步 | 是 |
| Go | github.com/warmbly/warmbly-go | Go 1.23+ | 是 |
安装
npm install warmbly也可通过 pnpm、yarn 和 bun 安装（pnpm add warmbly、yarn add warmbly、bun add warmbly）。在低于 22 的 Node 版本中，网关需要额外的 WebSocket 实现：安装可选的 ws 对等依赖后，SDK 会自动使用它。
pip install warmbly交互式 OAuth2 流程和安全令牌存储属于可选扩展：pip install "warmbly[oauth]"。需要 Python 3.10+。
go get github.com/warmbly/warmbly-go需要 Go 1.23+（自动分页迭代器使用 range-over-func）。
快速入门
在控制台的“设置”中创建 API 密钥，将其设为环境变量 WARMBLY_API_KEY，然后执行：
import { Warmbly } from "warmbly";
const warmbly = new Warmbly({ apiKey: process.env.WARMBLY_API_KEY });
// List campaigns (auto-paginated)
for await (const campaign of await warmbly.campaigns.list()) {
console.log(campaign.id, campaign.name);
}import os
from warmbly import Warmbly
client = Warmbly(api_key=os.environ["WARMBLY_API_KEY"])
for key in client.api_keys.list():
print(key.name, key.status)Warmbly() 会自行从环境中读取 WARMBLY_API_KEY；每个方法在 AsyncWarmbly 中都有对应的可等待异步版本。
package main
import (
"context"
"fmt"
"log"
"github.com/warmbly/warmbly-go"
)
func main() {
client, err := warmbly.New(warmbly.WithAPIKey("wmbly_..."))
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
page, err := client.Campaigns.List(ctx, nil)
if err != nil {
log.Fatal(err)
}
for campaign, err := range page.All(ctx) {
if err != nil {
log.Fatal(err)
}
fmt.Println(campaign.Name)
}
}身份验证
所有 SDK 均接受 Bearer 凭据，两种凭据都受同一套权限检查约束：
- 供自己的脚本使用的 API 密钥（前缀为
wmbly_） - 供代表工作区执行操作的应用使用的 OAuth 访问令牌（前缀为
wmat_）
// warmbly-js
new Warmbly({ apiKey: "wmbly_..." }); // API key
new Warmbly({ accessToken: "wmat_..." }); // OAuth access token# warmbly-py (falls back to WARMBLY_API_KEY when omitted; any bearer token works)
Warmbly(api_key="wmbly_...")// warmbly-go
warmbly.New(warmbly.WithAPIKey("wmbly_..."))
warmbly.New(warmbly.WithAccessToken("..."))完整的授权码流程和客户端凭据流程（包括 PKCE 和自动刷新令牌）见 OAuth。密钥格式、权限范围及轮换说明见身份验证。
各 SDK 的共同能力
- 覆盖整个 API 的强类型 REST 资源，包括邮箱、营销活动、联系人、统一收件箱、分析数据、模板、CRM、集成和 Webhook。
- 内置 OAuth2 流程：带 PKCE 的授权码流程和客户端凭据流程，以及通过编程方式管理 OAuth 应用的功能。
- 通过一条具备故障恢复能力的 WebSocket 连接使用实时网关，支持心跳、自动重连和会话恢复，并推送强类型事件。请参阅实时服务。
- 默认提供故障恢复机制：使用指数退避和随机抖动自动重试，支持
Retry-After，并通过幂等键安全地重试修改操作。 - 游标分页配合自动分页迭代器，让你无需自行跟踪游标即可遍历所有记录。
- 强类型错误包含
request_id和可供程序识别的错误码，可与具名错误标识进行匹配。请参阅错误码。 - 体积精简：warmbly-js 和 warmbly-go 均无运行时依赖。
无代码集成与自动化
更喜欢可视化构建工具？Warmbly 还提供社区 n8n 节点 n8n-nodes-warmbly，并有完善的 Zapier 和 Make 使用指南。