Python SDK

messagebird-sdk (nombre de importación bird) es el SDK oficial de Python para la API de Bird. Esta página cubre instalación, configuración, errores, reintentos, paginación y webhooks. Para enviar correo electrónico con el SDK, empieza con el quickstart de correo en Python.

Instalación

Ejemplo de código

pip install messagebird-sdk

Ejemplo de código

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

El paquete se publica como messagebird-sdk en PyPI, desde messagebird/bird-sdk-python.

Requiere Python 3.10+. El SDK está completamente tipado (py.typed), con modelos de respuesta Pydantic v2.

Crear un cliente

Elige entre dos clientes: Bird (sync) y AsyncBird (async). Ambos ofrecen los mismos métodos. Con AsyncBird, usa await en cada llamada y async for sobre listas. La configuración usa argumentos con nombre:

Ejemplo 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_ es la forma en Python del campo del protocolo from (from es una palabra reservada); el alias se gestiona automáticamente. Las respuestas son modelos Pydantic v2 que toleran campos desconocidos, así que un nuevo campo del servidor nunca rompe un cliente existente.

api_key y base_url recurren a las variables de entorno BIRD_API_KEY y BIRD_BASE_URL, así que Bird() sin argumentos funciona cuando están definidas. Usa el cliente como gestor de contexto (with Bird() as client: / async with AsyncBird() as client:) para cerrar el pool de conexiones subyacente. Construye un solo cliente y reutilízalo; ambos clientes se pueden compartir entre hilos o tareas de forma segura.

Configuración

Opción	Descripción
api_key	Clave API; recurre a BIRD_API_KEY.
region / base_url	Región (o URL base explícita); recurre al prefijo de la clave / BIRD_BASE_URL.
timeout, max_retries	Tiempo de espera de la solicitud y presupuesto de reintentos; se puede sobreescribir por llamada.
webhook_secret	Secreto de firma para client.webhooks.unwrap.
email_defaults	Valores predeterminados de send a nivel de cliente; un valor por envío siempre prevalece.
http_client	Inyecta tu propio httpx.Client / httpx.AsyncClient.

Cada método también acepta un options final para timeout / max_retries / idempotency_key / extra_headers por llamada, y client.with_options(...) deriva un nuevo cliente que reutiliza el pool de conexiones del padre:

Ejemplo 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},
)

Cómo está construido

Los modelos del protocolo se generan a partir de la especificación OpenAPI de Bird. Una capa escrita a mano proporciona la superficie curada de recursos (client.email, client.webhooks), argumentos con nombre explícitos y un ciclo de vida de solicitud compartido por todos los métodos. Consulta los conceptos de SDK para el modelo común entre SDK.

Errores

Los fallos lanzan excepciones tipadas con raíz en BirdError. APIError cubre los fallos de solicitud, incluidos fallos de transporte como tiempos de espera agotados, así que un solo except APIError gestiona cualquier llamada fallida. APIStatusError es el subconjunto devuelto por el servidor, que incluye status_code, request_id, code (el código estable de E#####) y type (la categoría de error general). Sus subclases incluyen RateLimitError (un 429, con retry_after en segundos) y ValidationError (un 422, con details por campo):

Ejemplo 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)

Los fallos exclusivos de transporte son APIConnectionError y APITimeoutError. Ambos son subclases de APIError, así que un except APIError amplio los captura. Una firma de webhook inválida lanza WebhookVerificationError.

Reintentos seguros

Los fallos transitorios, incluidos tiempos de espera agotados, respuestas 429 y respuestas 5xx, se reintentan automáticamente con retroceso aleatorizado que respeta Retry-After. Ajusta el presupuesto con max_retries, o usa cero para desactivar los reintentos. Una mutación genera una clave de idempotencia por llamada lógica y la reutiliza en cada intento. Pasa idempotency_key en el options por llamada para establecer la tuya.

Paginación

Los métodos de listado devuelven una página perezosa (SyncPage / AsyncPage); al iterar se pagina automáticamente a través de cursores, obteniendo páginas bajo demanda:

Ejemplo de código

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

Ejemplo de código

from bird import AsyncBird

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

Deja de iterar y no se obtienen más páginas.

Webhooks

client.webhooks.unwrap verifica una firma de Standard Webhooks sobre el cuerpo crudo de la solicitud y devuelve un evento tipado y discriminado. Configura el secreto de firma en el cliente (webhook_secret=) y pasa los bytes exactos que recibiste. Parsearlos y re-serializarlos rompe la firma:

Ejemplo 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)

La verificación no realiza ninguna llamada de red, así que funciona igual en cualquier framework web.

Alternativa directa

Los endpoints que aún no están en la superficie tipada son accesibles mediante client.get / post / put / patch / delete, con la misma autenticación, reintentos y gestión de idempotencia:

Ejemplo 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"})

Encuentra las rutas en la referencia de API.

Próximos pasos

Quickstart de correo en Python: Envía tu primer mensaje y usa send, get y list.
Conceptos de SDK: Aprende el modelo común entre SDK para errores, idempotencia, paginación y webhooks.
Referencia de API: Revisa el contrato HTTP subyacente.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Obtener un resumen de implementación