SDK अवधारणाएँ
TypeScript, Go, Python, और PHP SDK एक ही डिज़ाइन का पालन करते हैं। हर एक में types और एक low-level client के साथ एक generated base होता है, जो Bird की OpenAPI specification से बनाया गया है। एक hand-written layer request lifecycle को manage करता है और curated surface को expose करता है। यह पेज उनके साझा व्यवहार को कवर करता है। प्रत्येक भाषा के पेज idiomatic विवरण कवर करते हैं।
Auto-idempotency
हर mutation (POST, PUT, PATCH, DELETE) को एक auto-generated Idempotency-Key हेडर मिलता है। key प्रति logical call एक बार generate होती है और हर retry प्रयास में दोबारा उपयोग की जाती है। यह एक retried write को दो बार लागू होने से रोकता है। अगर send, server द्वारा process करने के बाद timeout हो जाता है, तो retry को stored response मिलता है। अपनी key पास करें (per-call idempotencyKey / option.WithIdempotencyKey / idempotency_key) जब logical operation एक से अधिक SDK call में फैला हो, जैसे SDK के आसपास एक application retry loop। सर्वर-साइड प्रोटोकॉल के लिए Idempotency देखें।
सुरक्षित retry
Retry डिफ़ॉल्ट रूप से चालू हैं (हर SDK में maxRetries: 2)। Client transient failures पर retry करता है, जिनमें network errors, per-attempt timeouts, 429 responses, और retryable 5xx responses शामिल हैं। यह jittered exponential backoff का उपयोग करता है और server के Retry-After हेडर का पालन करता है। Deterministic failures (401, 404, 422, और अन्य 4xx responses) पर कभी retry नहीं किया जाता। Idempotency key का पुन: उपयोग mutation retries को सुरक्षित बनाता है। Timeout प्रत्येक प्रयास पर लागू होता है (डिफ़ॉल्ट रूप से 60 सेकंड), इसलिए retries वाली call में अधिक समय लग सकता है। PHP, injected HTTP client द्वारा enforced timeout का उपयोग करता है क्योंकि PSR-18 में कोई portable per-request timeout नहीं है।
Pagination
List endpoints cursor-paginated हैं। हर SDK native iteration को सपोर्ट करता है, जो अगले pages को स्वचालित रूप से fetch करता है। Manual cursor control के लिए, single-page accessor का उपयोग करें। हर page में data और next_cursor शामिल होते हैं; आगे बढ़ने के लिए cursor को starting_after के रूप में वापस पास करें।
for await (const message of bird.email.list({ status: "bounced" })) {
console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursorfor message in client.email.list(status="delivered"):
print(message.id)
page = client.email.list(status="delivered") # page.data, page.next_cursor
print(len(page.data), page.next_cursor)for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusBounced}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id)
}
page, err := client.Email.ListPage(context.Background(), bird.EmailListParams{}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data)) // page.NextCursor carries the next starting_after$page = $bird->email->list(['status' => 'delivered'])->fetch();
foreach ($page->data as $message) {
echo $message->getId(), "\n";
}
$next = $page->nextCursor; // pass back as starting_after to fetch the next pageRegion inference
Bird API keys अपना region encode करती हैं: bk_{region}_{token}। SDK prefix पढ़ता है और स्वचालित रूप से https://{region}.platform.bird.com पर route करता है। एक region option inferred region को override करता है। एक explicit baseUrl (option.WithBaseURL / base_url) दोनों पर प्राथमिकता लेता है और local development या self-hosted deployments को सपोर्ट करता है। जब key bk_{region}_ format से मेल नहीं खाती और कोई override सेट नहीं है, तो construction विफल हो जाता है।
Per-call options बनाम construction-only config
Configuration के दो स्तर हैं। Identity और transport settings construction-only हैं: API key, base URL या region, और HTTP client या fetch implementation। Lifecycle settings को construction defaults के रूप में सेट किया जा सकता है और per call override किया जा सकता है: timeout, maxRetries, idempotency key, और extra headers। TypeScript, Python, और PHP एक trailing options object का उपयोग करते हैं; Go variadic option.With… options का उपयोग करता है। SDK-owned headers (Authorization, User-Agent, Idempotency-Key) caller-supplied headers पर प्राथमिकता लेते हैं। Channel defaults, जैसे एक default email from, उसी pattern का पालन करते हैं।
Webhook सत्यापन
हर SDK एक सत्यापन entry point प्रदान करता है: webhooks.unwrap(rawBody, headers)। यह raw पेलोड और आपके endpoint की signing secret पर HMAC-SHA256 के साथ Standard Webhooks implement करता है। यह v1-tagged signature entries स्वीकार करता है, 5-मिनट की tolerance window के बाहर timestamps को reject करता है, और signatures की constant time में तुलना करता है। Raw request body bytes को ठीक वैसे ही पास करें जैसे प्राप्त हुए हैं। JSON को parse और re-serialize करने से bytes बदल जाते हैं और signature अमान्य हो जाता है।
सफलता पर, unwrap एक typed event लौटाता है जो type पर discriminated होता है, जैसे email.delivered या email.bounced। अज्ञात event types भी verify और decode होते हैं, इसलिए उन्हें अपनी default branch में handle करें। सत्यापन विफलता एक अलग error है (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); 400 से respond करें। Endpoint setup और event catalog के लिए Webhooks देखें।
अगले कदम
- Quickstarts: अपनी भाषा और framework में अपना पहला email भेजें।
- Webhooks और events: एक endpoint सेट करें और unwrap के पीछे event catalog एक्सप्लोर करें।
- API संदर्भ: हर SDK द्वारा उपयोग किए जाने वाले HTTP contract की समीक्षा करें।
संबंधित संसाधन
इस विषय के लिए डॉक्यूमेंटेशन, गाइड और उदाहरणों के साथ आगे बढ़ें। संसाधन अंग्रेज़ी में हैं।
कॉन्सेप्ट समझेंShould I use a Bird SDK or call the API directly?लर्निंग पाथ फ़ॉलो करेंBuild your first integrationइम्प्लीमेंटेशन गाइडSend your first email
इम्प्लीमेंटेशन ब्रीफ़ पाएँ