Python SDK

messagebird-sdk (nama impor bird) adalah SDK Python resmi untuk Bird API. Halaman ini membahas instalasi, konfigurasi, error, retry, paginasi, dan webhook. Untuk mengirim email dengan SDK, mulai dari Panduan cepat email Python.

Instal

Contoh kode

pip install messagebird-sdk

Contoh kode

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

Paket ini dipublikasikan sebagai messagebird-sdk di PyPI, dari messagebird/bird-sdk-python.

Memerlukan Python 3.10+. SDK sepenuhnya bertipe (py.typed), dengan model respons Pydantic v2.

Membuat klien

Pilih salah satu dari dua klien: Bird (sync) dan AsyncBird (async). Keduanya menyediakan metode yang sama. Dengan AsyncBird, gunakan await untuk setiap panggilan dan async for untuk iterasi list. Konfigurasi menggunakan keyword argument:

Contoh kode

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_ adalah penulisan Python untuk field wire from (from adalah reserved word); alias ditangani secara otomatis. Respons berupa model Pydantic v2 yang mentoleransi field baru, sehingga field server baru tidak pernah merusak klien yang sudah ada.

api_key dan base_url menggunakan variabel lingkungan BIRD_API_KEY dan BIRD_BASE_URL sebagai fallback, sehingga Bird() tanpa argumen berfungsi ketika variabel tersebut sudah diatur. Gunakan klien sebagai context manager (with Bird() as client: / async with AsyncBird() as client:) untuk menutup connection pool. Buat satu klien dan gunakan ulang; kedua klien aman digunakan bersama lintas thread atau task.

Konfigurasi

Opsi	Deskripsi
api_key	Kunci API; fallback ke BIRD_API_KEY.
region / base_url	Region (atau base URL eksplisit); fallback ke prefiks kunci / BIRD_BASE_URL.
timeout, max_retries	Timeout permintaan dan anggaran retry; dapat di-override per panggilan.
webhook_secret	Signing secret untuk client.webhooks.unwrap.
email_defaults	Default send di level klien; nilai per pengiriman selalu menang.
http_client	Injeksikan httpx.Client / httpx.AsyncClient Anda sendiri.

Setiap metode juga menerima options di akhir untuk timeout / max_retries / idempotency_key / extra_headers per panggilan, dan client.with_options(...) membuat klien baru yang menggunakan ulang connection pool induk:

Contoh kode

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

Cara pembuatannya

Model wire dihasilkan dari spesifikasi OpenAPI Bird. Lapisan yang ditulis manual menyediakan permukaan resource terkurasi (client.email, client.webhooks), keyword argument eksplisit, dan siklus hidup request yang digunakan bersama oleh setiap metode. Lihat Konsep SDK untuk model lintas-SDK.

Error

Kegagalan melempar exception bertipe yang berakar di BirdError. APIError mencakup kegagalan request, termasuk kegagalan transport seperti timeout, sehingga satu except APIError menangani semua panggilan yang gagal. APIStatusError adalah subset yang dikembalikan server, membawa status_code, request_id, code (kode E##### yang stabil), dan type (kategori error kasar). Subclass-nya meliputi RateLimitError (429, dengan retry_after dalam detik) dan ValidationError (422, dengan details per field):

Contoh kode

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)

Kegagalan khusus transport adalah APIConnectionError dan APITimeoutError. Keduanya adalah subclass dari APIError, sehingga except APIError yang luas menangkapnya. Tanda tangan webhook yang tidak valid melempar WebhookVerificationError.

Retry aman

Kegagalan sementara, termasuk timeout, respons 429, dan respons 5xx, dicoba ulang secara otomatis dengan jittered backoff yang menghormati Retry-After. Atur anggaran retry dengan max_retries, atau gunakan nol untuk menonaktifkan retry. Mutasi menghasilkan satu kunci idempotensi per panggilan logis dan menggunakannya ulang di setiap percobaan. Kirim idempotency_key di options per panggilan untuk mengatur milik Anda sendiri.

Paginasi

Metode list mengembalikan halaman lazy (SyncPage / AsyncPage); mengiterasinya melakukan paginasi otomatis melalui cursor, mengambil halaman sesuai kebutuhan:

Contoh kode

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

Contoh kode

from bird import AsyncBird

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

Hentikan iterasi dan tidak ada halaman berikutnya yang diambil.

Webhook

client.webhooks.unwrap memverifikasi tanda tangan Standard Webhooks atas body request mentah dan mengembalikan event bertipe dan terdiskriminasi. Konfigurasikan signing secret pada klien (webhook_secret=), dan kirimkan byte persis yang Anda terima. Melakukan parsing dan serialisasi ulang akan merusak tanda tangan:

Contoh kode

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

Verifikasi tidak melakukan panggilan jaringan, sehingga bekerja sama di framework web mana pun.

Escape hatch

Endpoint yang belum tersedia di permukaan bertipe dapat diakses melalui client.get / post / put / patch / delete, dengan autentikasi, retry, dan penanganan idempotensi yang sama:

Contoh kode

from bird import EmailMessage

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

Temukan path di Referensi API.

Langkah selanjutnya

Panduan cepat email Python: Kirim pesan pertama Anda dan gunakan send, get, dan list.
Konsep SDK: Pelajari model lintas-SDK untuk error, idempotensi, paginasi, dan webhook.
Referensi API: Tinjau kontrak HTTP yang mendasarinya.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Dapatkan ringkasan implementasi