Python SDK
messagebird-sdk (nome de import bird) é o SDK Python oficial para a Bird API. Esta página cobre instalação, configuração, erros, retentativas, paginação e webhooks. Para enviar e-mail com o SDK, comece pelo Quickstart de e-mail em Python.
Instalação
Exemplo de código
pip install messagebird-sdkExemplo de código
# or
uv add messagebird-sdk
poetry add messagebird-sdkO pacote é publicado como messagebird-sdk no PyPI, a partir de messagebird/bird-sdk-python.
Requer Python 3.10+. O SDK é totalmente tipado (py.typed), com modelos de resposta Pydantic v2.
Criar um cliente
Escolha entre dois clientes: Bird (sync) e AsyncBird (async). Eles fornecem os mesmos métodos. Com AsyncBird, use await em cada chamada e async for em listas. A configuração usa argumentos nomeados:
Exemplo de código
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_ é a grafia Python do campo de rede from (from é uma palavra reservada); o alias é tratado automaticamente. As respostas são modelos Pydantic v2 que toleram campos desconhecidos, então um novo campo do servidor nunca quebra um cliente existente.
api_key e base_url recorrem às variáveis de ambiente BIRD_API_KEY e BIRD_BASE_URL, então Bird() sem argumentos funciona quando elas estão definidas. Use o cliente como gerenciador de contexto (with Bird() as client: / async with AsyncBird() as client:) para fechar o pool de conexões subjacente. Construa um único cliente e reutilize-o; ambos os clientes podem ser compartilhados entre threads ou tasks com segurança.
Configuração
| Opção | Descrição |
|---|---|
| api_key | Chave API; recorre a BIRD_API_KEY. |
| region / base_url | Região (ou URL base explícita); recorre ao prefixo da chave / BIRD_BASE_URL. |
| timeout, max_retries | Timeout da requisição e limite de retentativas; substituível por chamada. |
| webhook_secret | Segredo de assinatura para client.webhooks.unwrap. |
| email_defaults | Padrões de send para todo o cliente; um valor por envio sempre prevalece. |
| http_client | Injete seu próprio httpx.Client / httpx.AsyncClient. |
Todo método também aceita um options final para timeout / max_retries / idempotency_key / extra_headers por chamada, e client.with_options(...) deriva um novo cliente que reutiliza o pool de conexões do pai:
Exemplo de código
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},
)Como é construído
Os modelos de rede são gerados a partir da especificação OpenAPI da Bird. Uma camada escrita manualmente fornece a superfície curada de recursos (client.email, client.webhooks), argumentos nomeados explícitos e um ciclo de vida de requisição compartilhado por todos os métodos. Consulte conceitos do SDK para o modelo cross-SDK.
Erros
Falhas levantam exceções tipadas com raiz em BirdError. APIError cobre falhas de requisição, incluindo falhas de transporte como timeouts, então um único except APIError trata qualquer chamada com falha. APIStatusError é o subconjunto retornado pelo servidor, contendo status_code, request_id, code (o código E##### estável) e type (a categoria de erro genérica). Suas subclasses incluem RateLimitError (um 429, com retry_after em segundos) e ValidationError (um 422, com details por campo):
Exemplo de código
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)Falhas exclusivas de transporte são APIConnectionError e APITimeoutError. Ambas são subclasses de APIError, então um except APIError abrangente as captura. Uma assinatura de webhook inválida levanta WebhookVerificationError.
Retentativas seguras
Falhas transitórias, incluindo timeouts, respostas 429 e respostas 5xx, são retentadas automaticamente com backoff com jitter que respeita Retry-After. Ajuste o limite com max_retries, ou use zero para desativar retentativas. Uma mutação gera uma chave de idempotência por chamada lógica e a reutiliza em todas as tentativas. Passe idempotency_key no options por chamada para definir a sua própria.
Paginação
Métodos de listagem retornam uma página lazy (SyncPage / AsyncPage); iterar sobre ela pagina automaticamente entre cursores, buscando páginas sob demanda:
Exemplo de código
for message in client.email.list(status="delivered"):
print(message.id)Exemplo de código
from bird import AsyncBird
async with AsyncBird() as client:
async for message in client.email.list(status="delivered"):
print(message.id)Pare de iterar e nenhuma página adicional será buscada.
Webhooks
client.webhooks.unwrap verifica uma assinatura Standard Webhooks sobre o corpo bruto da requisição e retorna um evento tipado e discriminado. Configure o segredo de assinatura no cliente (webhook_secret=) e passe os bytes exatos que você recebeu. Fazer parse e re-serializar quebra a assinatura:
Exemplo de código
# 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)A verificação não faz nenhuma chamada de rede, então funciona da mesma forma em qualquer framework web.
Recurso alternativo
Endpoints ainda não disponíveis na superfície tipada podem ser acessados por client.get / post / put / patch / delete, com a mesma autenticação, retentativas e tratamento de idempotência:
Exemplo de código
from bird import EmailMessage
message = client.get("/v1/email/messages/em_01krd...", cast_to=EmailMessage)
client.post("/v1/some/new/endpoint", body={"key": "value"})Encontre os paths na referência da API.
Próximos passos
- Quickstart de e-mail em Python: Envie sua primeira mensagem e use send, get e list.
- Conceitos do SDK: Conheça o modelo cross-SDK para erros, idempotência, paginação e webhooks.
- Referência da API: Consulte o contrato HTTP subjacente.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Obtenha um resumo de implementação