Python SDK

messagebird-sdk (nom d'import bird) est le SDK Python officiel pour l'API Bird. Cette page couvre l'installation, la configuration, les erreurs, les réessais, la pagination et les webhooks. Pour envoyer un e-mail avec le SDK, commencez par le quickstart e-mail Python.

Installation

Exemple de code

pip install messagebird-sdk

Exemple de code

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

Le paquet est publié sous le nom messagebird-sdk sur PyPI, depuis messagebird/bird-sdk-python.

Requiert Python 3.10+. Le SDK est entièrement typé (py.typed), avec des modèles de réponse Pydantic v2.

Créer un client

Choisissez entre deux clients : Bird (sync) et AsyncBird (async). Ils exposent les mêmes méthodes. Avec AsyncBird, utilisez await pour chaque appel et async for sur les listes. La configuration utilise des arguments nommés :

Exemple de code

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_ est l'écriture Python du champ réseau from (from est un mot réservé) ; l'alias est géré automatiquement. Les réponses sont des modèles Pydantic v2 qui tolèrent les champs inconnus : un nouveau champ serveur ne casse jamais un client existant.

api_key et base_url se rabattent sur les variables d'environnement BIRD_API_KEY et BIRD_BASE_URL, donc Bird() sans arguments fonctionne lorsqu'elles sont définies. Utilisez le client comme gestionnaire de contexte (with Bird() as client: / async with AsyncBird() as client:) pour fermer le pool de connexions sous-jacent. Construisez un seul client et réutilisez-le ; les deux clients peuvent être partagés entre threads ou tâches en toute sécurité.

Configuration

Option	Description
api_key	Clé API ; se rabat sur BIRD_API_KEY.
region / base_url	Région (ou URL de base explicite) ; se rabat sur le préfixe de la clé / BIRD_BASE_URL.
timeout, max_retries	Délai d'attente de la requête et budget de réessai ; modifiables par appel.
webhook_secret	Secret de signature pour client.webhooks.unwrap.
email_defaults	Valeurs par défaut send à l'échelle du client ; une valeur par envoi l'emporte toujours.
http_client	Injectez votre propre httpx.Client / httpx.AsyncClient.

Chaque méthode accepte aussi un options en fin d'appel pour timeout / max_retries / idempotency_key / extra_headers par appel, et client.with_options(...) dérive un nouveau client qui réutilise le pool de connexions du parent :

Exemple de code

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

Architecture interne

Les modèles réseau sont générés à partir de la spécification OpenAPI de Bird. Une couche écrite manuellement fournit la surface de ressources organisée (client.email, client.webhooks), les arguments nommés explicites et un cycle de vie de requête partagé par chaque méthode. Consultez les concepts SDK pour le modèle cross-SDK.

Erreurs

Les échecs lèvent des exceptions typées dont la racine est BirdError. APIError couvre les échecs de requête, y compris les échecs de transport comme les délais d'attente, de sorte qu'un seul except APIError gère tout appel en échec. APIStatusError est le sous-ensemble renvoyé par le serveur, portant status_code, request_id, code (le code E##### stable) et type (la catégorie d'erreur générale). Ses sous-classes incluent RateLimitError (un 429, avec retry_after en secondes) et ValidationError (un 422, avec des details par champ) :

Exemple de code

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)

Les échecs purement liés au transport sont APIConnectionError et APITimeoutError. Tous deux sont des sous-classes de APIError, donc un except APIError large les intercepte. Une signature de webhook invalide lève WebhookVerificationError.

Réessais sûrs

Les échecs transitoires, y compris les délais d'attente, les réponses 429 et les réponses 5xx, sont réessayés automatiquement avec un backoff aléatoire qui respecte Retry-After. Ajustez le budget avec max_retries, ou utilisez zéro pour désactiver les réessais. Une mutation génère une clé d'idempotence par appel logique et la réutilise à chaque tentative. Passez idempotency_key dans le options par appel pour définir la vôtre.

Pagination

Les méthodes de liste renvoient une page paresseuse (SyncPage / AsyncPage) ; l'itération pagine automatiquement via les curseurs, en récupérant les pages à la demande :

Exemple de code

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

Exemple de code

from bird import AsyncBird

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

Arrêtez l'itération et aucune page supplémentaire n'est récupérée.

Webhooks

client.webhooks.unwrap vérifie une signature Standard Webhooks sur le corps brut de la requête et renvoie un événement typé et discriminé. Configurez le secret de signature sur le client (webhook_secret=), et transmettez les octets exacts que vous avez reçus. Les analyser puis les re-sérialiser casse la signature :

Exemple de code

# 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 vérification n'effectue aucun appel réseau ; elle fonctionne de la même façon dans n'importe quel framework web.

Solution de secours

Les endpoints pas encore exposés sur la surface typée sont accessibles via client.get / post / put / patch / delete, avec la même authentification, les mêmes réessais et la même gestion de l'idempotence :

Exemple de code

from bird import EmailMessage

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

Retrouvez les chemins dans la référence API.

Étapes suivantes

Quickstart e-mail Python : Envoyez votre premier message et utilisez send, get et list.
Concepts SDK : Découvrez le modèle cross-SDK pour les erreurs, l'idempotence, la pagination et les webhooks.
Référence API : Consultez le contrat HTTP sous-jacent.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation