Python SDK

messagebird-sdk（导入名 bird）是 Bird API 的官方 Python SDK。本页涵盖安装、配置、错误、重试、分页和 webhooks。如需通过 SDK 发送邮件，请从 Python 邮件快速入门开始。

安装

代码示例

pip install messagebird-sdk

代码示例

# or
uv add messagebird-sdk
poetry add messagebird-sdk

该包以 messagebird-sdk on PyPI 发布，源自 messagebird/bird-sdk-python。

需要 Python 3.10+。SDK 具有完整类型标注（py.typed），并使用 Pydantic v2 响应模型。

创建客户端

可选择两种客户端：Bird（同步）和 AsyncBird（异步）。两者提供相同的方法。使用 AsyncBird 时，对每次调用使用 await，对列表使用 async for。配置通过关键字参数传入：

代码示例

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    subject="Hello from Bird",
    html="<p>My first Bird email.</p>",
)
print(msg.id, msg.status)

from_ 是线路字段 from 的 Python 写法（from 是保留字）；别名已自动处理。响应是 Pydantic v2 模型，可容忍未知字段，因此服务端新增字段不会破坏现有客户端。

api_key 和 base_url 会回退到 BIRD_API_KEY 和 BIRD_BASE_URL 环境变量，因此在它们已设置时，不带参数的 Bird() 即可正常工作。使用客户端作为上下文管理器（with Bird() as client: / async with AsyncBird() as client:）以关闭底层连接池。只创建一个客户端并复用；两种客户端都可安全地跨线程或任务共享。

配置

选项	描述
api_key	API 密钥；回退到 BIRD_API_KEY。
region / base_url	区域（或显式 base URL）；回退到密钥前缀 / BIRD_BASE_URL。
timeout、max_retries	请求超时和重试预算；可按调用覆盖。
webhook_secret	client.webhooks.unwrap 的签名密钥。
email_defaults	客户端级 send 默认值；按次发送的值始终优先。
http_client	注入自定义的 httpx.Client / httpx.AsyncClient。

每个方法还接受尾部的 options，用于按调用设置 timeout / max_retries / idempotency_key / extra_headers；client.with_options(...) 会派生一个复用父级连接池的新客户端：

代码示例

client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    subject="Hello from Bird",
    text="My first Bird email.",
    options={"timeout": 10, "max_retries": 0},
)

构建方式

线路模型由 Bird 的 OpenAPI 规范生成。手写层提供精选的资源接口（client.email、client.webhooks）、显式关键字参数以及所有方法共享的请求生命周期。跨 SDK 模型请参阅 SDK concepts。

错误

失败会抛出以 BirdError 为根的类型化异常。APIError 涵盖请求失败，包括超时等传输失败，因此单个 except APIError 即可处理任何失败调用。APIStatusError 是服务端返回的子集，携带 status_code、request_id、code（稳定的 E##### 代码）和 type（粗粒度的错误类别)。其子类包括 RateLimitError（429，附带以秒为单位的 retry_after）和 ValidationError（422，附带按字段的 details）：

代码示例

from bird import APIStatusError, RateLimitError, ValidationError

try:
    client.email.send(
        from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
        to=["delivered@messagebird.dev"],
        subject="Hello from Bird",
        text="My first Bird email.",
    )
except RateLimitError as err:
    print("rate limited; retry after", err.retry_after)
except ValidationError as err:
    print(err.status_code, err.details)
except APIStatusError as err:
    print(err.status_code, err.code, err.request_id)

仅传输层的失败为 APIConnectionError 和 APITimeoutError。两者都是 APIError 的子类，因此宽泛的 except APIError 可以捕获它们。无效的 webhook 签名会抛出 WebhookVerificationError。

安全重试

瞬时失败，包括超时、429 响应和 5xx 响应，会自动以带抖动的退避策略重试，并遵守 Retry-After。使用 max_retries 调整重试预算，设为零可禁用重试。变更操作会为每次逻辑调用生成一个幂等键，并在每次尝试中复用。在按调用的 options 中传入 idempotency_key 以设置自定义键。

分页

列表方法返回惰性页（SyncPage / AsyncPage）；迭代时自动跨游标分页，按需获取页面：

代码示例

for message in client.email.list(status="delivered"):
    print(message.id)

代码示例

from bird import AsyncBird

async with AsyncBird() as client:
    async for message in client.email.list(status="delivered"):
        print(message.id)

停止迭代即不再获取后续页面。

Webhooks

client.webhooks.unwrap 验证原始请求体上的 Standard Webhooks 签名，并返回带类型的、可区分的事件。在客户端上配置签名密钥（webhook_secret=），并传入接收到的原始字节。对其进行解析再序列化会破坏签名：

代码示例

# Pass the RAW request body (bytes) and the request headers.
event = client.webhooks.unwrap(request.body, request.headers)
if event.root.type == "email.delivered":
    print(event.root.data.email_id)

验证不执行任何网络调用，因此在任何 Web 框架中行为一致。

兜底方法

尚未在类型化接口上的端点可通过 client.get / post / put / patch / delete 访问，享有相同的认证、重试和幂等处理：

代码示例

from bird import EmailMessage

message = client.get("/v1/email/messages/em_01krd...", cast_to=EmailMessage)
client.post("/v1/some/new/endpoint", body={"key": "value"})

可在 API 参考文档中查找路径。

后续步骤

Python 邮件快速入门：发送第一条消息并使用 send、get 和 list。
SDK concepts：了解跨 SDK 的错误、幂等、分页和 webhooks 模型。
API 参考文档：查阅底层 HTTP 契约。

相关资源