Python SDK
messagebird-sdk (importnaam bird) is de officiële Python SDK voor de Bird API. Deze pagina behandelt installatie, configuratie, fouten, retries, paginering en webhooks. Om e-mail te versturen met de SDK, begin je met de Python e-mail-quickstart.
Installeren
Codevoorbeeld
pip install messagebird-sdkCodevoorbeeld
# or
uv add messagebird-sdk
poetry add messagebird-sdkHet pakket is gepubliceerd als messagebird-sdk op PyPI, vanuit messagebird/bird-sdk-python.
Vereist Python 3.10+. De SDK is volledig getypeerd (py.typed), met Pydantic v2-responsmodellen.
Een client aanmaken
Kies tussen twee clients: Bird (sync) en AsyncBird (async). Ze bieden dezelfde methoden. Gebruik bij AsyncBird await voor elke aanroep en async for over lijsten. Configuratie gebruikt keyword-argumenten:
Codevoorbeeld
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_ is de Python-schrijfwijze van het wire-veld from (from is een gereserveerd woord); de alias wordt automatisch afgehandeld. Responses zijn Pydantic v2-modellen die onbekende velden tolereren, zodat een nieuw serverveld nooit een bestaande client breekt.
api_key en base_url vallen terug op de omgevingsvariabelen BIRD_API_KEY en BIRD_BASE_URL, dus Bird() zonder argumenten werkt als deze zijn ingesteld. Gebruik de client als contextmanager (with Bird() as client: / async with AsyncBird() as client:) om de onderliggende connectionpool te sluiten. Maak één client aan en hergebruik deze; beide clients zijn veilig te delen tussen threads of taken.
Configuratie
| Optie | Beschrijving |
|---|---|
| api_key | API-sleutel; valt terug op BIRD_API_KEY. |
| region / base_url | Regio (of expliciete basis-URL); valt terug op het sleutelprefix / BIRD_BASE_URL. |
| timeout, max_retries | Requesttime-out en retrybudget; per aanroep te overschrijven. |
| webhook_secret | Ondertekeningsgeheim voor client.webhooks.unwrap. |
| email_defaults | Clientbrede send-standaardwaarden; een waarde per verzending wint altijd. |
| http_client | Injecteer je eigen httpx.Client / httpx.AsyncClient. |
Elke methode accepteert ook een afsluitende options voor per-aanroep timeout / max_retries / idempotency_key / extra_headers, en client.with_options(...) leidt een nieuwe client af die de connectionpool van de parent hergebruikt:
Codevoorbeeld
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},
)Hoe het is opgebouwd
De wire-modellen worden gegenereerd uit de OpenAPI-specificatie van Bird. Een handgeschreven laag biedt het samengestelde resource-oppervlak (client.email, client.webhooks), expliciete keyword-argumenten en een requestlevenscyclus die elke methode deelt. Zie SDK-concepten voor het cross-SDK-model.
Fouten
Fouten gooien getypeerde exceptions met als basis BirdError. APIError dekt requestfouten, inclusief transportfouten zoals time-outs, zodat één except APIError elke mislukte aanroep afhandelt. APIStatusError is de door de server geretourneerde subset, met status_code, request_id, code (de stabiele E#####-code) en type (de grove foutcategorie). Subklassen zijn onder andere RateLimitError (een 429, met retry_after in seconden) en ValidationError (een 422, met per-veld details):
Codevoorbeeld
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)Alleen-transportfouten zijn APIConnectionError en APITimeoutError. Beide zijn subklassen van APIError, dus een brede except APIError vangt ze op. Een ongeldige webhookhandtekening gooit WebhookVerificationError.
Veilige retries
Tijdelijke fouten, waaronder time-outs, 429-responses en 5xx-responses, worden automatisch opnieuw geprobeerd met jittered backoff die Retry-After respecteert. Stel het budget in met max_retries, of gebruik nul om retries uit te schakelen. Een mutatie genereert één idempotentiesleutel per logische aanroep en hergebruikt deze bij elke poging. Geef idempotency_key mee in de per-aanroep options om je eigen sleutel in te stellen.
Paginering
Lijstmethoden retourneren een lazy pagina (SyncPage / AsyncPage); itereren pagineert automatisch over cursors en haalt pagina's op wanneer nodig:
Codevoorbeeld
for message in client.email.list(status="delivered"):
print(message.id)Codevoorbeeld
from bird import AsyncBird
async with AsyncBird() as client:
async for message in client.email.list(status="delivered"):
print(message.id)Stop met itereren en er worden geen verdere pagina's opgehaald.
Webhooks
client.webhooks.unwrap verifieert een Standard Webhooks-handtekening over de ruwe requestbody en retourneert een getypeerd, gediscrimineerd event. Configureer het ondertekeningsgeheim op de client (webhook_secret=) en geef de exacte bytes door die je hebt ontvangen. Parsen en opnieuw serialiseren breekt de handtekening:
Codevoorbeeld
# 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)Verificatie voert geen netwerkverzoek uit, dus het werkt hetzelfde in elk webframework.
Noodluik
Endpoints die nog niet op het getypeerde oppervlak staan, zijn bereikbaar via client.get / post / put / patch / delete, met dezelfde authenticatie, retries en idempotentieafhandeling:
Codevoorbeeld
from bird import EmailMessage
message = client.get("/v1/email/messages/em_01krd...", cast_to=EmailMessage)
client.post("/v1/some/new/endpoint", body={"key": "value"})Vind de paden in de API-referentie.
Volgende stappen
- Python e-mail-quickstart: Verstuur je eerste bericht en gebruik send, get en list.
- SDK-concepten: Leer het cross-SDK-model voor fouten, idempotentie, paginering en webhooks.
- API-referentie: Bekijk het onderliggende HTTP-contract.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integrationImplementatiegidsSend your first email
Ontvang een implementatieoverzicht