TypeScript SDK

@messagebird/sdk 是 Bird API 的官方 TypeScript SDK。它具有完整类型定义，仅支持 ESM，并且适用于边缘环境。它运行在 Node.js 20.3+ 和现代边缘运行时（Cloudflare Workers、Vercel Edge、Deno）上，使用 Web 标准 API（fetch、AbortSignal、Web Crypto）。本页介绍客户端。要使用 SDK 发送邮件，请从 TypeScript 邮件快速入门开始。

安装

代码示例

npm install @messagebird/sdk
# pnpm add @messagebird/sdk
# yarn add @messagebird/sdk
# bun add @messagebird/sdk

该包以 @messagebird/sdk 发布在 npm 上，源自 messagebird/bird-sdk-typescript。

构造客户端

代码示例

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY!,
  region: "eu1", // optional; overrides the region from the key prefix
  baseUrl: "http://localhost:8080", // optional; overrides region (local or self-hosted)
  timeout: 60_000, // per-attempt timeout in ms (default 60_000)
  maxRetries: 2, // retry budget for transient failures (default 2)
});

只有 apiKey 是必需的。区域通过密钥的 bk_{region}_ 前缀推断（bk_eu1_… 密钥路由到 https://eu1.platform.bird.com），因此大多数客户端仅需密钥即可构造。解析规则见区域推断。你还可以在构造时设置渠道默认值（例如 email: { from: "hello@acme.com" } 使每次发送时 from 变为可选），并通过 webhooks: { secret } 设置 webhook 签名密钥。

第一次调用

代码示例

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

await 直接解析为 API 结果，在本例中是一封包含其 em_* ID 的邮件消息。如需可运行的完整演练，请参阅 TypeScript 快速入门。

双层设计

SDK 包含一个生成层和一个手动维护层。线上类型和底层 HTTP 管道从 Bird 的 OpenAPI 规范生成，使请求和响应结构与契约保持一致。手写层提供 bird.email.send(...)、重试、幂等性、分页和错误处理。线上字段以 snake_case 形式传递（category、created_at）；SDK 定义的标识符（如方法名和 idempotencyKey）使用 camelCase。Go 和 Python SDK 共享此架构。详情见 SDK 概念。

自动幂等性和重试

每个修改操作（POST、PUT、PATCH、DELETE）都会获得自动生成的 Idempotency-Key 请求头。SDK 在每次重试时复用该键，因此匹配的重试可以重放保留的响应。有关不同 SDK 调用之间的自定义键和重放限制，请参阅幂等性。

重试默认开启（maxRetries: 2）。客户端对网络故障、单次尝试超时和瞬态状态码（408、429、500、502、503、504）进行重试，使用带抖动的指数退避策略，并在服务器返回 Retry-After 请求头时予以遵循。确定性失败（如 401、404、422 等 4xx）不会被重试。设置 maxRetries: 0 可禁用重试，也可按单次调用覆盖。完整生命周期见 SDK 概念。

错误

方法在失败时抛出带类型层次的异常，你可以用 instanceof 进行收窄。BirdError 是根类。BirdAPIError 覆盖来自服务器的所有错误响应，每种错误 type 有一个子类。包括 BirdAuthError（401）、BirdRateLimitError（429，附带 retryAfter）、BirdValidationError（422，附带逐字段 details）和 BirdPayloadTooLargeError（413）。没有 HTTP 响应的传输故障使用同级类 BirdConnectionError 和 BirdTimeoutError。

代码示例

import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

每个 BirdAPIError 携带 statusCode、type、code（稳定的 E##### 错误码）、requestId 和 docUrl。通过类（或粗粒度的 type）进行控制流分支；需要匹配特定失败时使用 code。更倾向于基于值分支而非捕获异常？每个调用还提供 .safe()：

代码示例

const { data, error } = await bird.email
  .send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  })
  .safe();
if (error) console.error(error.message);
else console.log(data.id);

Webhooks

bird.webhooks.unwrap(rawBody, headers) 验证入站投递的 Standard Webhooks 签名，并返回带类型的可辨识事件。请传入原始请求体，因为解析后重新序列化会改变已签名的字节。无效签名、过期时间戳或格式错误的请求头会抛出 BirdWebhookVerificationError。跨 SDK 契约见 webhook 验证，平台配置见 Webhooks。

后续步骤

邮件快速入门：使用 send、get、list、渠道默认值和响应结构。
SDK 概念：了解所有 Bird SDK 的幂等性、重试、分页、区域和 webhooks。
API 参考：查阅底层 HTTP API。bird.request<T>() 可访问类型化接口尚未覆盖的端点，并具有相同的认证、重试和幂等性。

相关资源