Python SDK

messagebird-sdk (Importname bird) ist das offizielle Python SDK für die Bird API. Diese Seite behandelt Installation, Konfiguration, Fehler, Wiederholungen, Paginierung und Webhooks. Um E-Mails mit dem SDK zu senden, beginnen Sie mit dem Python-E-Mail-Schnellstart.

Installieren

Codebeispiel

pip install messagebird-sdk

Codebeispiel

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

Das Paket ist als messagebird-sdk auf PyPI veröffentlicht, aus messagebird/bird-sdk-python.

Erfordert Python 3.10+. Das SDK ist vollständig typisiert (py.typed), mit Pydantic-v2-Antwortmodellen.

Client erstellen

Wählen Sie zwischen zwei Clients: Bird (sync) und AsyncBird (async). Beide bieten dieselben Methoden. Verwenden Sie bei AsyncBird für jeden Aufruf await und async for für Listen. Die Konfiguration erfolgt über Keyword-Argumente:

Codebeispiel

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_ ist die Python-Schreibweise des Wire-Felds from (from ist ein reserviertes Wort); der Alias wird automatisch verarbeitet. Antworten sind Pydantic-v2-Modelle, die unbekannte Felder tolerieren, sodass ein neues Serverfeld keinen bestehenden Client beschädigt.

api_key und base_url greifen auf die Umgebungsvariablen BIRD_API_KEY und BIRD_BASE_URL zurück, sodass Bird() ohne Argumente funktioniert, wenn diese gesetzt sind. Verwenden Sie den Client als Kontextmanager (with Bird() as client: / async with AsyncBird() as client:), um den zugrunde liegenden Verbindungspool zu schließen. Erstellen Sie einen Client und verwenden Sie ihn wieder; beide Clients können sicher über Threads oder Tasks geteilt werden.

Konfiguration

Option	Beschreibung
api_key	API-Schlüssel; greift auf BIRD_API_KEY zurück.
region / base_url	Region (oder explizite Basis-URL); greift auf das Schlüsselpräfix / BIRD_BASE_URL zurück.
timeout, max_retries	Anfrage-Timeout und Wiederholungsbudget; pro Aufruf überschreibbar.
webhook_secret	Signaturgeheimnis für client.webhooks.unwrap.
email_defaults	Clientweite send-Standardwerte; ein Wert pro Sendung hat immer Vorrang.
http_client	Eigenen httpx.Client / httpx.AsyncClient einbringen.

Jede Methode akzeptiert außerdem ein abschließendes options für timeout / max_retries / idempotency_key / extra_headers pro Aufruf, und client.with_options(...) leitet einen neuen Client ab, der den Verbindungspool des Eltern-Clients wiederverwendet:

Codebeispiel

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

Aufbau

Die Wire-Modelle werden aus der OpenAPI-Spezifikation von Bird generiert. Eine handgeschriebene Schicht stellt die kuratierte Ressourcenoberfläche (client.email, client.webhooks), explizite Keyword-Argumente und einen gemeinsamen Request-Lebenszyklus für jede Methode bereit. Siehe SDK-Konzepte für das SDK-übergreifende Modell.

Fehler

Fehler lösen typisierte Ausnahmen aus, die bei BirdError verwurzelt sind. APIError deckt Anfragefehler ab, einschließlich Transportfehler wie Timeouts, sodass ein einzelnes except APIError jeden fehlgeschlagenen Aufruf abfängt. APIStatusError ist die vom Server zurückgegebene Teilmenge mit status_code, request_id, code (der stabile E#####-Code) und type (die grobe Fehlerkategorie). Unterklassen umfassen RateLimitError (ein 429, mit retry_after in Sekunden) und ValidationError (ein 422, mit feldbezogenen details):

Codebeispiel

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)

Reine Transportfehler sind APIConnectionError und APITimeoutError. Beide sind Unterklassen von APIError, sodass ein breites except APIError sie abfängt. Eine ungültige Webhook-Signatur löst WebhookVerificationError aus.

Sichere Wiederholungen

Vorübergehende Fehler, einschließlich Timeouts, 429-Antworten und 5xx-Antworten, werden automatisch mit zufällig gestreuter Verzögerung wiederholt, die Retry-After berücksichtigt. Passen Sie das Budget mit max_retries an, oder verwenden Sie Null, um Wiederholungen zu deaktivieren. Eine Mutation erzeugt einen Idempotenzschlüssel pro logischem Aufruf und verwendet ihn bei jedem Versuch wieder. Übergeben Sie idempotency_key in den options pro Aufruf, um einen eigenen festzulegen.

Paginierung

List-Methoden geben eine Lazy Page zurück (SyncPage / AsyncPage); beim Iterieren wird automatisch über Cursor paginiert und Seiten werden bei Bedarf abgerufen:

Codebeispiel

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

Codebeispiel

from bird import AsyncBird

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

Beenden Sie die Iteration, und es werden keine weiteren Seiten abgerufen.

Webhooks

client.webhooks.unwrap verifiziert eine Standard-Webhooks-Signatur über den rohen Request-Body und gibt ein typisiertes, diskriminiertes Event zurück. Konfigurieren Sie das Signaturgeheimnis am Client (webhook_secret=), und übergeben Sie die exakten empfangenen Bytes. Parsen und erneutes Serialisieren bricht die Signatur:

Codebeispiel

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

Die Verifizierung führt keinen Netzwerkaufruf durch, funktioniert also in jedem Web-Framework gleich.

Notausgang

Endpunkte, die noch nicht auf der typisierten Oberfläche verfügbar sind, erreichen Sie über client.get / post / put / patch / delete, mit derselben Authentifizierung, denselben Wiederholungen und derselben Idempotenzbehandlung:

Codebeispiel

from bird import EmailMessage

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

Die Pfade finden Sie in der API-Referenz.

Nächste Schritte

Python-E-Mail-Schnellstart: Senden Sie Ihre erste Nachricht und verwenden Sie send, get und list.
SDK-Konzepte: Lernen Sie das SDK-übergreifende Modell für Fehler, Idempotenz, Paginierung und Webhooks kennen.
API-Referenz: Prüfen Sie den zugrunde liegenden HTTP-Vertrag.

Verwandte Ressourcen