Python SDK

messagebird-sdk (import नाम bird) Bird API के लिए आधिकारिक Python SDK है। इस पेज में इंस्टॉलेशन, कॉन्फ़िगरेशन, त्रुटियाँ, फिर से प्रयास, पेजिनेशन और वेबहुक शामिल हैं। SDK से ईमेल भेजने के लिए Python ईमेल क्विकस्टार्ट से शुरू करें।

इंस्टॉल करें

pip install messagebird-sdk

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

यह पैकेज messagebird/bird-sdk-python से PyPI पर messagebird-sdk के रूप में प्रकाशित है।

इसके लिए Python 3.10+ आवश्यक है। SDK पूरी तरह टाइप किया गया है (py.typed), और इसके रिस्पॉन्स मॉडल Pydantic v2 पर आधारित हैं।

क्लाइंट बनाएँ

दो क्लाइंट में से एक चुनें: Bird (sync) और AsyncBird (async)। दोनों में एक जैसे मेथड हैं। AsyncBird के साथ हर कॉल के लिए await और सूचियों पर async for का उपयोग करें। कॉन्फ़िगरेशन keyword arguments से होता है:

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_ वायर फ़ील्ड from का Python रूप है, क्योंकि from एक आरक्षित शब्द है। यह alias अपने आप संभाला जाता है। रिस्पॉन्स Pydantic v2 मॉडल हैं जो अज्ञात फ़ील्ड स्वीकार कर लेते हैं, इसलिए सर्वर पर नया फ़ील्ड जुड़ने से मौजूदा क्लाइंट कभी नहीं टूटता।

api_key और base_url न दिए जाने पर BIRD_API_KEY और BIRD_BASE_URL environment variables का उपयोग होता है, इसलिए इनके सेट होने पर बिना arguments के Bird() काम करता है। अंदर के connection pool को बंद करने के लिए क्लाइंट को context manager (with Bird() as client: / async with AsyncBird() as client:) के रूप में उपयोग करें। एक क्लाइंट बनाएँ और उसे दोबारा उपयोग करें। दोनों क्लाइंट को threads या tasks के बीच सुरक्षित रूप से साझा किया जा सकता है।

कॉन्फ़िगरेशन

हर मेथड प्रति-कॉल timeout / max_retries / idempotency_key / extra_headers के लिए अंत में एक options भी लेता है, और client.with_options(...) एक नया क्लाइंट बनाता है जो पैरेंट क्लाइंट का कनेक्शन पूल दोबारा इस्तेमाल करता है:

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

यह कैसे बना है

वायर मॉडल Bird के OpenAPI स्पेसिफिकेशन से जनरेट किए जाते हैं। हाथ से लिखी गई एक परत चुनी हुई रिसोर्स सतह (client.email, client.webhooks), स्पष्ट कीवर्ड आर्ग्युमेंट और हर मेथड में साझा अनुरोध जीवनचक्र देती है। सभी SDK में साझा मॉडल के लिए SDK अवधारणाएँ देखें।

त्रुटियाँ

विफलता होने पर BirdError से शुरू होने वाले टाइप किए गए अपवाद उठाए जाते हैं। APIError अनुरोध की विफलताओं को कवर करता है, जिनमें टाइमआउट जैसी ट्रांसपोर्ट विफलताएँ भी शामिल हैं, इसलिए एक ही except APIError किसी भी विफल कॉल को संभाल लेता है। APIStatusError सर्वर द्वारा लौटाई गई विफलताओं का उपसमूह है, जिसमें status_code, request_id, code (स्थिर E##### कोड) और type (मोटी त्रुटि श्रेणी) होते हैं। इसके उपवर्गों में RateLimitError (429, सेकंड में retry_after के साथ) और ValidationError (422, प्रति-फ़ील्ड details के साथ) शामिल हैं:

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)

केवल ट्रांसपोर्ट से जुड़ी विफलताएँ APIConnectionError और APITimeoutError हैं। दोनों APIError के उपवर्ग हैं, इसलिए एक व्यापक except APIError इन्हें पकड़ लेता है। गलत webhook हस्ताक्षर होने पर WebhookVerificationError उठाया जाता है।

सुरक्षित रूप से फिर से प्रयास करना

अस्थायी विफलताओं, जैसे टाइमआउट, 429 प्रतिक्रियाओं और 5xx प्रतिक्रियाओं, पर SDK जिटर वाले बैकऑफ़ के साथ अपने-आप फिर से प्रयास करता है, जो Retry-After का पालन करता है। max_retries से बजट समायोजित करें, या फिर से प्रयास बंद करने के लिए शून्य दें। हर बदलाव वाला कॉल प्रति तार्किक कॉल एक idempotency कुंजी बनाता है और हर प्रयास में उसी को दोबारा इस्तेमाल करता है। अपनी कुंजी सेट करने के लिए प्रति-कॉल options में idempotency_key पास करें।

पेजिनेशन

सूची वाले मेथड एक लेज़ी पेज (SyncPage / AsyncPage) लौटाते हैं; इस पर इटरेट करने से यह कर्सर के पार अपने-आप पेजिनेट करता है और ज़रूरत पड़ने पर पेज लाता है:

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

from bird import AsyncBird

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

इटरेशन रोकते ही आगे के पेज फ़ेच नहीं किए जाते।

वेबहुक

client.webhooks.unwrap रॉ अनुरोध बॉडी पर Standard Webhooks सिग्नेचर का सत्यापन करता है और एक टाइप्ड, डिस्क्रिमिनेटेड इवेंट लौटाता है। साइनिंग सीक्रेट क्लाइंट पर कॉन्फ़िगर करें (webhook_secret=), और ठीक वही बाइट्स पास करें जो आपको मिले थे। उन्हें पार्स करके दोबारा सीरियलाइज़ करने से सिग्नेचर टूट जाता है:

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

सत्यापन कोई नेटवर्क कॉल नहीं करता, इसलिए यह हर वेब फ़्रेमवर्क में एक जैसा काम करता है।

वैकल्पिक रास्ता

जो एंडपॉइंट अभी टाइप्ड सतह पर नहीं हैं, उन तक client.get / post / put / patch / delete के ज़रिए पहुँचा जा सकता है, उसी ऑथ, फिर से प्रयास और आइडेम्पोटेंसी हैंडलिंग के साथ:

from bird import EmailMessage

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

पाथ API संदर्भ में देखें।

अगले कदम

• Python ईमेल क्विकस्टार्ट: अपना पहला संदेश भेजें और send, get और list का उपयोग करें।
• SDK अवधारणाएँ: त्रुटियों, आइडेम्पोटेंसी, पेजिनेशन और वेबहुक के लिए सभी SDK में साझा मॉडल जानें।
• API संदर्भ: मूल HTTP अनुबंध देखें।