बैच भेजना
POST /v1/email/batches एक अनुरोध में 100 तक पूर्ण सेंड पेलोड स्वीकार करता है। हर आइटम अपने स्वयं के प्रेषक, प्राप्तकर्ताओं और सामग्री के साथ एक स्वतंत्र संदेश है। रसीदें, अलर्ट या अन्य प्रति-प्राप्तकर्ता संदेश कम API अनुरोधों में जमा करने के लिए बैच का उपयोग करें। एक संदेश के लिए, ईमेल भेजना देखें।
कब क्या उपयोग करें
- स्वतंत्र संदेश जो आपके पास पहले से तैयार हैं। बैच का उपयोग करें और उन्हें एक ही अनुरोध में सौंप दें।
- एक स्थिर उच्च-मात्रा वाली धारा। सिंगल-सेंड एंडपॉइंट को लूप में कॉल करना एक ठोस आर्किटेक्चर है, और बैच किसी एक संदेश को सस्ता या तेज़ डिलीवर नहीं करता। यह जो बदलता है वह थ्रूपुट है, क्योंकि बैच अनुरोध email_send ग्रुप की बजाय email_batch दर-सीमा ग्रुप से लिए जाते हैं, और हर एक में 100 तक संदेश होते हैं।
- एक स्टोर्ड ऑडियंस को एक ईमेल। यह एक ब्रॉडकास्ट है, जो ऑडियंस को प्राप्तकर्ताओं में रिज़ॉल्व करता है और प्रति कॉन्टैक्ट पर्सनलाइज़ करता है।
बैच सेंड
रिक्वेस्ट बॉडी एक JSON ऑब्जेक्ट है जिसकी messages ऐरे में 1 से 100 तक मैसेज ऑब्जेक्ट होते हैं। हर आइटम अपने स्वयं के from, to, subject, सामग्री, और वैकल्पिक रूप से अपने category, ip_pool_id, टैग्स और मेटाडेटा के साथ एक पूर्ण, स्वतंत्र सेंड रिक्वेस्ट है। आइटम स्कीमा बिल्कुल सिंगल-सेंड पेलोड जैसा है, इसलिए ईमेल भेजना में बताई गई हर बात प्रति आइटम लागू होती है, जिसमें category का डिफ़ॉल्ट marketing और टेम्पलेट से भेजना शामिल है।
इसमें scheduled_at भी शामिल है, इसलिए एक बैच ऐसे संदेशों को मिला सकता है जो अभी जाएँ और जो बाद में जाएँ, हर एक अपने समय पर। शेड्यूल्ड भेजना के नियम और सीमा प्रति आइटम लागू होती है, और एक शेड्यूल्ड आइटम किसी भी अन्य शेड्यूल्ड संदेश की तरह अपनी ID से रद्द किया जाता है।
const batch = await bird.email.sendBatch({
messages: [
{
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["alice@example.com"],
subject: "Your receipt",
html: "<p>Thanks, Alice.</p>",
},
{
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["bob@example.com"],
subject: "Your receipt",
html: "<p>Thanks, Bob.</p>",
},
],
});
for (const item of batch.data) console.log(item.id, item.status);batch = client.email.send_batch(
messages=[
{
"from_": {"email": "onboarding@messagebird.dev", "name": "Bird"},
"to": ["delivered@messagebird.dev"],
"subject": "Hello from Bird",
"html": "<p>My first Bird email.</p>",
},
{
"from_": {"email": "onboarding@messagebird.dev", "name": "Bird"},
"to": ["someone-else@messagebird.dev"],
"subject": "Hello again from Bird",
"text": "My second Bird email.",
},
],
)
for item in batch.data:
print(item.id, item.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
batch, err := client.Email.SendBatch(context.Background(), bird.EmailSendBatchParams{
Messages: []bird.EmailSendParams{
{
From: "onboarding@messagebird.dev",
To: []string{"alice@example.com"},
Subject: "Hello, Alice",
HTML: "<p>Welcome!</p>",
},
{
From: "onboarding@messagebird.dev",
To: []string{"bob@example.com"},
Subject: "Hello, Bob",
HTML: "<p>Welcome!</p>",
},
},
})
if err != nil {
log.Fatal(err)
}
for _, item := range batch.Data {
fmt.Println(item.Id)
}
}$batch = $bird->email->sendBatch(messages: [
(new EmailMessageSendRequest())
->setFrom((new EmailAddress())->setEmail('onboarding@messagebird.dev')->setName('Bird'))
->setTo([(new EmailAddress())->setEmail('delivered@messagebird.dev')])
->setSubject('Hello from Bird')
->setHtml('<p>My first Bird email.</p>'),
(new EmailMessageSendRequest())
->setFrom((new EmailAddress())->setEmail('onboarding@messagebird.dev')->setName('Bird'))
->setTo([(new EmailAddress())->setEmail('someone-else@messagebird.dev')])
->setSubject('Hello again from Bird')
->setText('My second Bird email.'),
]);
foreach ($batch->getData() ?? [] as $item) {
echo $item->getId(), ' ', $item->getStatus(), "\n";
}bird email send-batch --body-file - <<'JSON'
{
"messages": [
{
"from": {
"email": "noreply@acme.com",
"name": "Acme Support"
},
"to": [
{
"email": "delivered@messagebird.dev",
"name": "Jane Doe"
}
],
"subject": "Your receipt for order #1234",
"text": "Thanks for your purchase! Your receipt is attached."
},
{
"from": {
"email": "noreply@acme.com",
"name": "Acme Support"
},
"to": [
{
"email": "delivered@messagebird.dev",
"name": "John Roe"
}
],
"subject": "Your receipt for order #1235",
"text": "Thanks for your purchase! Your receipt is attached."
}
]
}
JSON{
"name": "email_send_batch",
"arguments": {
"messages": [
{
"from": {
"email": "noreply@acme.com",
"name": "Acme Support"
},
"subject": "Your receipt for order #1234",
"text": "Thanks for your purchase! Your receipt is attached.",
"to": [
{
"email": "delivered@messagebird.dev",
"name": "Jane Doe"
}
]
},
{
"from": {
"email": "noreply@acme.com",
"name": "Acme Support"
},
"subject": "Your receipt for order #1235",
"text": "Thanks for your purchase! Your receipt is attached.",
"to": [
{
"email": "delivered@messagebird.dev",
"name": "John Roe"
}
]
}
]
}
}curl -X POST https://us1.platform.bird.com/v1/email/batches \
-H "Authorization: Bearer bk_us1_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: batch-2026-07-23-001" \
-d '{
"messages": [
{
"from": "hello@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>",
"category": "transactional"
},
{
"from": "newsletter@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "June product news",
"html": "<p>What shipped this month.</p>",
"category": "marketing"
},
{
"from": "alerts@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Usage threshold reached",
"text": "You have used 80% of your quota.",
"category": "transactional"
}
]
}'सब-या-कुछ-नहीं सत्यापन
किसी भी आइटम को कतार में डालने से पहले हर आइटम को सत्यापित किया जाता है। अगर एक संदेश विफल होता है, चाहे फ़ील्ड-स्तरीय सत्यापन त्रुटि हो या असत्यापित प्रेषक डोमेन, तो पूरा बैच 422 के साथ अस्वीकार कर दिया जाता है और कुछ भी नहीं भेजा जाता: उस आइटम को ठीक करें और बैच दोबारा जमा करें।
सप्रेशन इस जाँच का हिस्सा नहीं है। जिस आइटम के सभी प्राप्तकर्ता सप्रेस्ड हैं वह फिर भी स्वीकार होता है और उसे अपना em_ ID मिलता है, और संदेश प्रोसेस होने पर वे प्राप्तकर्ता status: rejected के रूप में वापस आते हैं (देखें सप्रेशन)।
202 रिस्पॉन्स को हैंडल करें
एक सफल बैच 202 Accepted लौटाता है जिसमें प्रति संदेश एक एंट्री होती है, जमा करने के क्रम में:
कोड उदाहरण
{
"data": [
{ "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
{ "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
{ "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
]
}हर चाइल्ड एक सामान्य संदेश है: इसे उसकी em_ ID से GET /v1/email/messages/{message_id}, उसके प्राप्तकर्ता और इवेंट एंडपॉइंट्स, और वेबहुक्स के माध्यम से ट्रैक करें, बिल्कुल वैसे ही जैसे आपने इसे अलग से भेजा हो। वही async मॉडल लागू होता है, इसलिए 202 का मतलब है कि संदेश स्थायी रूप से स्वीकार हो गया है और प्रति-प्राप्तकर्ता परिणाम बाद में आते हैं।
इडेम्पोटेंट रिट्राई
बैच के साथ एक Idempotency-Key हेडर भेजें, जैसा कि उदाहरण अनुरोध में किया गया है। अगर अनुरोध सफल हो गया लेकिन आपने रिस्पॉन्स नहीं देखा, तो उसी key के साथ दोबारा भेजने पर मूल परिणाम मिलता है, वही चाइल्ड मैसेज ID और एक Idempotency-Replay हेडर, बजाय हर संदेश को फिर से भेजने के। यहाँ एक आकस्मिक डुप्लिकेट की कीमत 100 तक ईमेल हो सकती है, इसलिए प्रोडक्शन में key को अनिवार्य मानें। देखें इडेम्पोटेंसी।
अटैचमेंट और बॉडी सीमा
हर बैच आइटम के अपने attachments हो सकते हैं, उसी फ़ील्ड कॉन्ट्रैक्ट और प्रति-संदेश साइज़ बजट पर जो सिंगल सेंड में होता है (देखें अटैचमेंट)। बैच पर समग्र रूप से एक और सीमा लागू होती है: सीरियलाइज़्ड JSON रिक्वेस्ट बॉडी अधिकतम 20 MB है, और इससे बड़ी बॉडी 413 के साथ अस्वीकार कर दी जाती है। Base64-एन्कोडेड अटैचमेंट इसमें गिने जाते हैं, इसलिए अटैचमेंट-भारी बैच जल्दी सीमा तक पहुँच जाते हैं। उन्हें कई बैचों में बाँटें, या एक-एक करके भेजें।
ब्रॉडकास्ट
ब्रॉडकास्ट एक स्टोर्ड ऑडियंस को एक ईमेल भेजता है। सेंड शुरू होने पर हम ऑडियंस के वर्तमान सदस्यों को, सप्रेशन घटाकर, प्राप्तकर्ता सूची में रिज़ॉल्व करते हैं, और हर प्राप्तकर्ता की कॉन्टैक्ट प्रॉपर्टीज़ टेम्पलेट के वेरिएबल्स भरती हैं। डैशबोर्ड से, /v1/email/broadcasts से, या bird email broadcasts कमांड से ब्रॉडकास्ट चलाएँ। ब्रॉडकास्ट में पूरा वॉकथ्रू है।
अगले कदम
- ईमेल भेजना: प्रति-आइटम पेलोड पूर्ण रूप में, जिसमें फ़ील्ड्स, सीमाएँ, और टैग्स बनाम मेटाडेटा शामिल हैं
- ब्रॉडकास्ट: एक स्टोर्ड ऑडियंस को एक ईमेल, प्रति कॉन्टैक्ट पर्सनलाइज़्ड
- कैटेगरी: marketing और transactional, और हर एक सप्रेशन पॉलिसी पर क्या प्रभाव डालता है
- इडेम्पोटेंसी: key फ़ॉर्मैट, रिटेंशन, और रीप्ले सिमैंटिक्स
- API रेफ़रेंस: पूर्ण बैच रिक्वेस्ट और रिस्पॉन्स स्कीमा
- एक API कॉल में 100 ईमेल भेजें: एक वीडियो जो दिखाता है कि बैच कैसे जाता है और हर संदेश कैसे रिपोर्ट करता है
संबंधित संसाधन
इस विषय के लिए डॉक्यूमेंटेशन, गाइड और उदाहरणों के साथ आगे बढ़ें। संसाधन अंग्रेज़ी में हैं।