Python SDK

messagebird-sdk (nazwa importu bird) to oficjalny SDK Pythona dla Bird API. Ta strona obejmuje instalację, konfigurację, błędy, ponawianie, paginację i webhooki. Aby wysłać e-mail za pomocą SDK, zacznij od szybkiego startu z e-mailem w Pythonie.

Instalacja

Przykład kodu

pip install messagebird-sdk

Przykład kodu

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

Pakiet jest opublikowany jako messagebird-sdk na PyPI, z repozytorium messagebird/bird-sdk-python.

Wymaga Pythona 3.10+. SDK jest w pełni typowany (py.typed), z modelami odpowiedzi Pydantic v2.

Tworzenie klienta

Wybierz jednego z dwóch klientów: Bird (sync) i AsyncBird (async). Udostępniają te same metody. W przypadku AsyncBird używaj await dla każdego wywołania i async for do iteracji po listach. Konfiguracja odbywa się przez argumenty nazwane:

Przykład kodu

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_ to pythonowa forma pola sieciowego from (from to słowo zastrzeżone); alias jest obsługiwany automatycznie. Odpowiedzi to modele Pydantic v2 tolerujące nieznane pola, więc nowe pole po stronie serwera nigdy nie zepsuje istniejącego klienta.

api_key i base_url korzystają domyślnie ze zmiennych środowiskowych BIRD_API_KEY i BIRD_BASE_URL, więc Bird() bez argumentów działa, gdy są ustawione. Używaj klienta jako menedżera kontekstu (with Bird() as client: / async with AsyncBird() as client:), aby zamknąć pulę połączeń. Utwórz jednego klienta i używaj go ponownie; oba typy klientów można bezpiecznie współdzielić między wątkami i zadaniami.

Konfiguracja

Opcja	Opis
api_key	Klucz API; domyślnie pobierany z BIRD_API_KEY.
region / base_url	Region (lub jawny bazowy URL); domyślnie pobierany z prefiksu klucza / BIRD_BASE_URL.
timeout, max_retries	Limit czasu żądania i budżet ponowień; nadpisywalne per wywołanie.
webhook_secret	Sekret podpisujący dla client.webhooks.unwrap.
email_defaults	Domyślne wartości send na poziomie klienta; wartość per wysyłkę zawsze ma pierwszeństwo.
http_client	Wstrzyknij własny httpx.Client / httpx.AsyncClient.

Każda metoda przyjmuje również końcowy options do ustawiania per wywołanie timeout / max_retries / idempotency_key / extra_headers, a client.with_options(...) tworzy nowego klienta współdzielącego pulę połączeń rodzica:

Przykład kodu

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

Jak to jest zbudowane

Modele sieciowe są generowane ze specyfikacji OpenAPI Bird. Ręcznie napisana warstwa udostępnia kuratorowaną powierzchnię zasobów (client.email, client.webhooks), jawne argumenty nazwane i cykl życia żądania wspólny dla każdej metody. Zobacz koncepcje SDK, aby poznać model wspólny dla wszystkich SDK.

Błędy

Niepowodzenia zgłaszają typowane wyjątki wywodzące się z BirdError. APIError obejmuje błędy żądań, w tym błędy transportowe takie jak przekroczenie limitu czasu, więc pojedynczy except APIError obsłuży każde nieudane wywołanie. APIStatusError to podzbiór zwracany przez serwer, zawierający status_code, request_id, code (stabilny kod E#####) i type (ogólna kategoria błędu). Jego podklasy obejmują RateLimitError (429, z retry_after w sekundach) i ValidationError (422, z details per pole):

Przykład kodu

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)

Błędy wyłącznie transportowe to APIConnectionError i APITimeoutError. Oba są podklasami APIError, więc ogólny except APIError je przechwytuje. Nieprawidłowy podpis webhooka zgłasza WebhookVerificationError.

Bezpieczne ponawianie

Przejściowe błędy, w tym przekroczenia limitu czasu, odpowiedzi 429 i odpowiedzi 5xx, są ponawiane automatycznie z losowym wycofywaniem uwzględniającym Retry-After. Dostosuj budżet za pomocą max_retries lub ustaw zero, aby wyłączyć ponawianie. Mutacja generuje jeden klucz idempotentności na wywołanie logiczne i używa go ponownie przy każdej próbie. Przekaż idempotency_key w options per wywołanie, aby ustawić własny.

Paginacja

Metody listujące zwracają leniwą stronę (SyncPage / AsyncPage); iteracja po niej automatycznie przechodzi przez kursory, pobierając strony na żądanie:

Przykład kodu

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

Przykład kodu

from bird import AsyncBird

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

Przerwij iterację, a kolejne strony nie zostaną pobrane.

Webhooki

client.webhooks.unwrap weryfikuje podpis Standard Webhooks na surowym ciele żądania i zwraca typowane, dyskryminowane zdarzenie. Skonfiguruj sekret podpisujący na kliencie (webhook_secret=) i przekaż dokładne bajty, które otrzymałeś. Parsowanie i ponowna serializacja niszczą podpis:

Przykład kodu

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

Weryfikacja nie wykonuje żadnego wywołania sieciowego, więc działa tak samo w każdym frameworku webowym.

Wyjście awaryjne

Endpointy niedostępne jeszcze na typowanej powierzchni są osiągalne przez client.get / post / put / patch / delete, z tą samą autoryzacją, ponawianiem i obsługą idempotentności:

Przykład kodu

from bird import EmailMessage

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

Znajdź ścieżki w referencji API.

Następne kroki

Szybki start z e-mailem w Pythonie: Wyślij pierwszą wiadomość i użyj send, get i list.
Koncepcje SDK: Poznaj model wspólny dla wszystkich SDK dotyczący błędów, idempotentności, paginacji i webhooków.
Referencja API: Przejrzyj bazowy kontrakt HTTP.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy