Python SDK
messagebird-sdk (nome di import bird) è l'SDK Python ufficiale per Bird API. Questa pagina tratta installazione, configurazione, errori, retry, paginazione e webhook. Per inviare email con l'SDK, parti dalla guida rapida email per Python.
Installazione
Esempio di codice
pip install messagebird-sdkEsempio di codice
# or
uv add messagebird-sdk
poetry add messagebird-sdkIl pacchetto è pubblicato come messagebird-sdk su PyPI, dal repository messagebird/bird-sdk-python.
Richiede Python 3.10+. L'SDK è completamente tipizzato (py.typed), con modelli di risposta Pydantic v2.
Creare un client
Scegli tra due client: Bird (sync) e AsyncBird (async). Espongono gli stessi metodi. Con AsyncBird, usa await per ogni chiamata e async for sulle liste. La configurazione usa argomenti con nome:
Esempio di codice
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_ è la forma Python del campo wire from (from è una parola riservata); l'alias è gestito automaticamente. Le risposte sono modelli Pydantic v2 che tollerano campi sconosciuti, quindi un nuovo campo del server non rompe mai un client esistente.
api_key e base_url ricadono sulle variabili d'ambiente BIRD_API_KEY e BIRD_BASE_URL, quindi Bird() senza argomenti funziona quando sono impostate. Usa il client come context manager (with Bird() as client: / async with AsyncBird() as client:) per chiudere il pool di connessioni sottostante. Costruisci un solo client e riutilizzalo; entrambi i client possono essere condivisi tra thread o task in sicurezza.
Configurazione
| Opzione | Descrizione |
|---|---|
| api_key | Chiave API; ricade su BIRD_API_KEY. |
| region / base_url | Regione (o URL base esplicito); ricade sul prefisso della chiave / BIRD_BASE_URL. |
| timeout, max_retries | Timeout della richiesta e budget di retry; sovrascrivibili per singola chiamata. |
| webhook_secret | Signing secret per client.webhooks.unwrap. |
| email_defaults | Valori predefiniti send a livello di client; un valore per singolo invio ha sempre la precedenza. |
| http_client | Inietta il tuo httpx.Client / httpx.AsyncClient. |
Ogni metodo accetta anche un options finale per timeout / max_retries / idempotency_key / extra_headers per singola chiamata, e client.with_options(...) deriva un nuovo client che riutilizza il pool di connessioni del genitore:
Esempio di codice
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},
)Com'è costruito
I modelli wire sono generati dalla specifica OpenAPI di Bird. Un livello scritto a mano fornisce la superficie di risorse curata (client.email, client.webhooks), argomenti con nome espliciti e un ciclo di vita della richiesta condiviso da ogni metodo. Consulta i concetti SDK per il modello cross-SDK.
Errori
I fallimenti sollevano eccezioni tipizzate con radice BirdError. APIError copre i fallimenti di richiesta, inclusi i fallimenti di trasporto come i timeout, quindi un singolo except APIError gestisce qualsiasi chiamata fallita. APIStatusError è il sottoinsieme restituito dal server, che contiene status_code, request_id, code (il codice E##### stabile) e type (la categoria di errore generica). Le sue sottoclassi includono RateLimitError (un 429, con retry_after in secondi) e ValidationError (un 422, con details per campo):
Esempio di codice
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)I fallimenti esclusivamente di trasporto sono APIConnectionError e APITimeoutError. Entrambi sono sottoclassi di APIError, quindi un except APIError generico li intercetta. Una firma webhook non valida solleva WebhookVerificationError.
Retry sicuri
I fallimenti transitori, inclusi timeout, risposte 429 e risposte 5xx, vengono riprovati automaticamente con backoff jittered che rispetta Retry-After. Regola il budget con max_retries, oppure usa zero per disabilitare i retry. Una mutazione genera una chiave di idempotenza per chiamata logica e la riutilizza in ogni tentativo. Passa idempotency_key nel options per singola chiamata per impostarne una personalizzata.
Paginazione
I metodi di lista restituiscono una pagina lazy (SyncPage / AsyncPage); iterarla pagina automaticamente attraverso i cursori, recuperando le pagine su richiesta:
Esempio di codice
for message in client.email.list(status="delivered"):
print(message.id)Esempio di codice
from bird import AsyncBird
async with AsyncBird() as client:
async for message in client.email.list(status="delivered"):
print(message.id)Interrompi l'iterazione e nessuna ulteriore pagina viene recuperata.
Webhook
client.webhooks.unwrap verifica una firma Standard Webhooks sul corpo grezzo della richiesta e restituisce un evento tipizzato e discriminato. Configura il signing secret sul client (webhook_secret=) e passa i byte esatti ricevuti. Fare il parsing e ri-serializzarli invalida la firma:
Esempio di codice
# 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 verifica non effettua chiamate di rete, quindi funziona allo stesso modo in qualsiasi web framework.
Scappatoia
Gli endpoint non ancora presenti sulla superficie tipizzata sono raggiungibili tramite client.get / post / put / patch / delete, con la stessa autenticazione, gli stessi retry e la stessa gestione dell'idempotenza:
Esempio di codice
from bird import EmailMessage
message = client.get("/v1/email/messages/em_01krd...", cast_to=EmailMessage)
client.post("/v1/some/new/endpoint", body={"key": "value"})Trova i percorsi nel reference API.
Passi successivi
- Guida rapida email per Python: invia il tuo primo messaggio e usa send, get e list.
- Concetti SDK: scopri il modello cross-SDK per errori, idempotenza, paginazione e webhook.
- Reference API: consulta il contratto HTTP sottostante.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione