ईमेल भेजना

POST /v1/email/messages एक ईमेल भेजता है। JSON पेलोड में प्रेषक, प्राप्तकर्ता और सामग्री दें। API एक संदेश ID के साथ 202 Accepted लौटाता है, फिर ईमेल को एसिंक्रोनस रूप से डिलीवर करता है। पूरे स्कीमा के लिए API संदर्भ देखें।

न्यूनतम भेजना

सबसे छोटे मान्य पेलोड में एक from, कम से कम एक to प्राप्तकर्ता, एक subject और एक बॉडी (html, text या दोनों) होते हैं। from पता ऐसे डोमेन पर होना चाहिए जिसे आपने इस वर्कस्पेस में सत्यापित किया है, या ऑनबोर्डिंग डोमेन पर।

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

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)

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)
	}
	msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
		From:    "onboarding@messagebird.dev",
		To:      []string{"delivered@messagebird.dev"},
		Subject: "Hello from Bird",
		HTML:    "<p>My first Bird email.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --from hello@yourdomain.com \
  --html '<p>It works.</p>' \
  --subject 'Hello from Bird' \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Hello from Bird",
    "html": "<p>It works.</p>"
  }'

अपने क्षेत्रीय होस्ट (https://us1.platform.bird.com या https://eu1.platform.bird.com) के साथ मेल खाने वाली bk_{region}_... कुंजी का उपयोग करें।

भेजने के उदाहरण में delivered@messagebird.dev का उपयोग होता है, जो एक सैंडबॉक्स पता है और हमेशा मेल स्वीकार करता है। API प्लेसहोल्डर डोमेन को 422 के साथ अस्वीकार करता है: example.com, example.net, example.org, example.edu, test.com, और आरक्षित .test, .example, .invalid या .localhost TLD के अंतर्गत कोई भी डोमेन। इन डोमेन पर भेजा गया मेल केवल बाउंस हो सकता है, जिससे आपकी प्रेषक प्रतिष्ठा घटती है।

डोमेन सत्यापित करने से पहले भेजना

ऑनबोर्डिंग के दौरान आप हमारे साझा ऑनबोर्डिंग डोमेन onboarding@messagebird.dev से भेज सकते हैं। ऐसे मेल डोमेन जाँच से नहीं गुजरते, लेकिन केवल आपके अपने वर्कस्पेस के सत्यापित सदस्यों और सैंडबॉक्स पतों तक पहुँचते हैं, और उन पर प्रतिदिन प्राप्तकर्ताओं की एक सीमा लागू होती है। सटीक नियम और सीमाएँ क्विकस्टार्ट में हैं।

पेलोड तैयार करना

प्राप्तकर्ता

to, cc और bcc में से हर एक में अधिकतम 50 पते दिए जा सकते हैं, और to में कम से कम एक पता होना चाहिए। हर प्रविष्टि एक सादा ईमेल स्ट्रिंग, एक RFC 5322 मेलबॉक्स स्ट्रिंग (Jane <jane@acme.com>), या वैकल्पिक प्रदर्शन नाम वाला एक ऑब्जेक्ट होती है।

वर्कस्पेस की सप्रेशन सूची में शामिल प्राप्तकर्ताओं के कारण अनुरोध विफल नहीं होता। अनुरोध फिर भी 202 लौटाता है, और हर सप्रेस किया गया प्राप्तकर्ता पढ़ने वाले एंडपॉइंट पर status: rejected के रूप में recipient_suppressed कारण के साथ लौटता है, तब भी जब भेजे गए संदेश के सभी प्राप्तकर्ता सप्रेस किए गए हों।

सामग्री

इनलाइन भेजने के लिए subject आवश्यक है, अधिकतम 998 अक्षर। html, text या दोनों दें, हर एक अधिकतम 524,288 अक्षर। जहाँ संभव हो, दोनों भेजें: जो क्लाइंट HTML नहीं दिखा सकता, वह टेक्स्ट भाग दिखाता है।

इनलाइन सामग्री को वैयक्तिकृत करने के लिए विषय या बॉडी में {{ variable }} टोकन रखें और उनके मान parameters में दें, सीरियलाइज़ होने पर अधिकतम 16 KB। मानों का एक ही सेट भेजे गए संदेश के सभी प्राप्तकर्ताओं पर लागू होता है, और जिस टोकन की कोई मेल खाती कुंजी नहीं है, वह खाली दिखता है। बार-बार इस्तेमाल होने वाली सामग्री के लिए इसके बजाय टेम्पलेट भेजें।

विषय और बॉडी को Liquid के रूप में प्रोसेस कराने के लिए parameters शामिल करें, चाहे खाली ऑब्जेक्ट ({}) के रूप में ही हो। अगर आप इसे छोड़ देते हैं, तो {{ animal }} जैसे टोकन ठीक वैसे ही भेजे जाते हैं जैसे लिखे गए हैं। हर पैरामीटर का नाम एक ही शब्द होता है, जैसे first_name; बिंदु वाले नाम और आरक्षित नाम bird अस्वीकार किए जाते हैं। अमान्य Liquid सिंटैक्स और असमर्थित टैग या फ़िल्टर 422 लौटाते हैं।

HTML में डाले गए मान एस्केप किए जाते हैं, ताकि वे आसपास के मार्कअप को न बदल सकें। पूरे लिंक या इमेज URL के लिए url_encode के बिना {{ link }} इस्तेमाल करें। URL क्वेरी के अंदर के मान को स्पष्ट रूप से एन्कोड करें, उदाहरण के लिए https://example.com/search?q={{ query | url_encode }}।

जवाब देने का पता और कस्टम हेडर

reply_to में 1 से 25 पते दिए जा सकते हैं, उन्हीं फ़ॉर्मैट में जो प्राप्तकर्ताओं के लिए हैं। प्राप्तकर्ता का हर जवाब इन सभी पतों पर जाता है, इसलिए आम तौर पर एक या दो पते दिए जाते हैं।

headers आपके अपने हेडर के लिए स्ट्रिंग से स्ट्रिंग वाला ऑब्जेक्ट है, उदाहरण के लिए {"X-Campaign": "spring-2026"}। इसमें अधिकतम 25 हेडर हो सकते हैं, और हर मान अधिकतम 998 अक्षर का हो सकता है। दो तरह के हेडर 422 लौटाते हैं:

पते और प्लेटफ़ॉर्म वाले हेडर। संदेश के पते उनके लिए बने फ़ील्ड (from, to, cc, bcc, reply_to, subject) से सेट करें। ये नाम, और हमारे द्वारा आपके लिए बनाए जाने वाले हेडर (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), यहाँ सेट नहीं किए जा सकते।
कैरिज रिटर्न या लाइन फ़ीड वाला कोई भी मान।

ट्रांज़ैक्शनल भेजने में List-Unsubscribe और List-Unsubscribe-Post स्वीकार किए जाते हैं। मार्केटिंग भेजने में डिफ़ॉल्ट रूप से Bird द्वारा प्रबंधित सदस्यता समाप्ति इस्तेमाल होती है।

ट्रैकिंग

track_opens और track_clicks दोनों का डिफ़ॉल्ट मान true है। इस भेजे गए संदेश में ओपन-पिक्सेल जोड़ना या लिंक बदलना छोड़ने के लिए किसी एक को false पर सेट करें। ये फ़्लैग आपकी सबमिट की गई सामग्री में पहले से मौजूद ट्रैकिंग पिक्सेल और लिंक को नहीं बदलते। हर विकल्प संदेश में क्या बदलता है, यह ट्रैकिंग और मेट्रिक्स में बताया गया है।

श्रेणी और IP पूल

category सामग्री को वर्गीकृत करता है और सप्रेशन नीति तय करता है। marketing हर सप्रेशन कारण और किसी भी ऑप्ट-आउट पर डिलीवरी रोकता है। transactional शिकायत वाले सप्रेशन या केवल मार्केटिंग वाले ऑप्ट-आउट के बावजूद डिलीवर करता है, पर सभी संदेशों के लिए दर्ज ऑप्ट-आउट इसे भी रोकता है। टेम्पलेट से भेजने पर इसका डिफ़ॉल्ट टेम्पलेट की श्रेणी होती है और अन्यथा marketing, इसलिए रसीदों, पासवर्ड रीसेट और अन्य परिचालन मेल के लिए transactional स्पष्ट रूप से सेट करें। सही चुनाव श्रेणियाँ में बताया गया है। SMTP के ज़रिए सबमिट किए गए मेल की श्रेणी इसके बजाय कुंजी के SMTP कॉन्फ़िगरेशन से आती है।

ip_pool_id भेजने का पूल चुनता है: कोई पूल ID (ipp_...), या साझा पूल से स्पष्ट रूप से भेजने के लिए ipp_shared। अपने संगठन का डिफ़ॉल्ट पूल इस्तेमाल करने के लिए इसे छोड़ दें। अज्ञात पूल, या ऐसा पूल जिसमें भेजने के लिए कोई समर्पित IP उपलब्ध न हो, 422 के साथ अस्वीकार कर दिया जाता है।

फ़ील्ड संदर्भ

फ़ील्ड	प्रकार	आवश्यक	सीमाएँ और टिप्पणियाँ
`from`	पता	हाँ	किसी सत्यापित डोमेन पर या ऑनबोर्डिंग डोमेन पर होना चाहिए
`to`	पता[]	हाँ	1 से 50
`cc`, `bcc`	पता[]	नहीं	प्रत्येक में अधिकतम 50
`subject`	स्ट्रिंग	इनलाइन भेजने पर	अधिकतम 998 अक्षर; टेम्पलेट से भेजते समय इसे छोड़ दें
`html`, `text`	स्ट्रिंग	कम से कम एक	प्रत्येक अधिकतम 524,288 अक्षर; टेम्पलेट से भेजते समय इन्हें छोड़ दें
`reply_to`	पता[]	नहीं	1 से 25; जवाब सूची के हर पते पर जाते हैं
`headers`	ऑब्जेक्ट (स्ट्रिंग → स्ट्रिंग)	नहीं	अधिकतम 25; आरक्षित नाम अस्वीकार किए जाते हैं (देखें कस्टम हेडर)
`parameters`	ऑब्जेक्ट	नहीं	इनलाइन सामग्री में `{{ tokens }}` के मान; सीरियलाइज़ होने पर अधिकतम 16 KB; सभी प्राप्तकर्ताओं के लिए साझा
`tags`	`{name, value}[]`	नहीं	अधिकतम 20; नाम ≤ 32 वर्ण, मान ≤ 64 वर्ण; केवल `[A-Za-z0-9_-]`; हर भेजने में नाम अद्वितीय होने चाहिए
`metadata`	ऑब्जेक्ट	नहीं	कोई भी JSON, सीरियलाइज़ होने पर अधिकतम 2 KB
`reference`	स्ट्रिंग	नहीं	1–255 अक्षर; संदेश सूची पर `?reference=` के लिए सटीक मिलान
`track_opens`	बूलियन	नहीं	डिफ़ॉल्ट `true`
`track_clicks`	बूलियन	नहीं	डिफ़ॉल्ट `true`
`category`	स्ट्रिंग	नहीं	`marketing` या `transactional`; टेम्पलेट से भेजने पर डिफ़ॉल्ट रूप से टेम्पलेट की श्रेणी, अन्यथा `marketing`
`ip_pool_id`	स्ट्रिंग	नहीं	`ipp_...` या `ipp_shared`; अपने संगठन के डिफ़ॉल्ट पूल के लिए इसे छोड़ दें
`template`	ऑब्जेक्ट	नहीं	प्रकाशित टेम्पलेट को `id` या `slug` से भेजें, उसके वेरिएबल के लिए `parameters` और वैकल्पिक `language` के साथ
`attachments`	ऑब्जेक्ट[]	नहीं	अधिकतम 20; देखें अटैचमेंट
`scheduled_at`	RFC 3339 टाइमस्टैम्प	नहीं	इनलाइन सामग्री या `template` को शेड्यूल करें; देखें शेड्यूल किया गया भेजना

टेम्पलेट के साथ भेजना

टेम्पलेट हर To पते से मेल खाने वाले संपर्क के bird.contact.* मान इस्तेमाल कर सकते हैं। Cc और Bcc प्राप्तकर्ताओं को हर To प्राप्तकर्ता के वैयक्तिकृत ईमेल की एक प्रति मिलती है। यह बैच API में और शेड्यूल किए गए भेजने में भी काम करता है; एक से ज़्यादा प्राप्तकर्ताओं वाले उदाहरण के लिए वेरिएबल से वैयक्तिकरण देखें।

इनलाइन सामग्री के बजाय कोई प्रकाशित टेम्पलेट भेजें: template को एक ऑब्जेक्ट पर सेट करें, जो टेम्पलेट को id (emt_...) या slug से पहचानता हो, इन दोनों में से ठीक एक से। उसके वेरिएबल के मान template.parameters में दें। subject, html और text न भेजें, क्योंकि ये टेम्पलेट में पहले से मौजूद हैं।

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  category: "transactional",
  template: {
    slug: "welcome-email",
    parameters: { first_name: "Jane" },
  },
});
console.log(msg.id, msg.status);

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    category="transactional",
    template="welcome-email",
    parameters={"first_name": "Jane"},
)
print(msg.id, msg.status)

msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:       "onboarding@messagebird.dev",
	To:         []string{"delivered@messagebird.dev"},
	Category:   "transactional",
	Template:   "welcome-email",
	Parameters: map[string]any{"first_name": "Jane"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    category: 'transactional',
    template: (new EmailMessageSendRequestTemplate())
        ->setSlug('welcome-email')
        ->setParameters(['first_name' => 'Jane']),
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --category transactional \
  --from hello@yourdomain.com \
  --parameters '{"first_name":"Jane"}' \
  --template welcome-email \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "category": "transactional",
    "template": {
      "slug": "welcome-email",
      "parameters": { "first_name": "Jane" }
    }
  }'

टेम्पलेट की सामग्री Liquid में होती है, इसलिए साधारण {{ variable }} प्रतिस्थापन के अलावा इसमें फ़िल्टर, {% if %} शर्तें और {% for %} लूप इस्तेमाल हो सकते हैं। वेरिएबल से वैयक्तिकरण उन कुछ संरचनाओं की सूची देता है जिन्हें प्रकाशन अस्वीकार करता है। template.parameters में आप टेम्पलेट के अपने पैरामीटर के मान नाम के अनुसार रखते हैं। अगर कोई मान छूट जाए, तो भेजना 422 के साथ अस्वीकार होता है, जिसमें उस पैरामीटर का नाम होता है। इस भेजने में इनलाइन ईमेल की तरह ही tags, metadata, ट्रैकिंग और अटैचमेंट समर्थित हैं। टेम्पलेट से भेजने की खास बातें:

इनलाइन या टेम्पलेट, दोनों एक साथ कभी नहीं। template के साथ subject, html या text भेजने पर अनुरोध 422 के साथ अस्वीकार होता है। API शीर्ष-स्तरीय parameters फ़ील्ड में वेरिएबल के मान भी अस्वीकार करता है; टेम्पलेट से भेजते समय ये मान template.parameters में जाते हैं।
bird ही एकमात्र आरक्षित नाम है। bird. से शुरू होने वाला प्लेसहोल्डर पथ हमारे अपने डेटा को दर्शाता है, जैसे अनसब्सक्राइब लिंक या प्राप्तकर्ता का संपर्क रिकॉर्ड, इसलिए किसी template.parameters कुंजी का नाम bird नहीं हो सकता। बाकी हर कुंजी आप खुद तय करते हैं, और हर कुंजी एक सपाट, एक-शब्द वाला नाम होती है: {"order_number": "A-1043"} से {{ order_number }} भरता है।
टेम्पलेट अभी या बाद में भेजा जा सकता है। भेजने को शेड्यूल करने के लिए scheduled_at जोड़ें। स्वीकार करते समय हम प्रकाशित संस्करण, चुनी गई भाषा, कॉल करने वाले के पैरामीटर और संपर्क के मान सहेज लेते हैं, इसलिए संपर्क या फ़ॉलबैक में बाद में किए गए बदलाव स्वीकार किए गए संदेशों को नहीं बदलते। अगर आप भेजने के समय से पहले टेम्पलेट हटा देते हैं, तो संदेश generation_failure के साथ अस्वीकार कर दिया जाता है।
संपर्क विशेषताओं से वैयक्तिकृत करें। संपर्क की आवश्यकताएँ और डिफ़ॉल्ट अभिवादन देखें।
संपर्क मिलान में डिस्प्ले नाम अनदेखे किए जाते हैं। ईमेल पते छोटे अक्षरों में बदले जाते हैं; डॉट और प्लस टैग बने रहते हैं। अगर कई संपर्कों का यही पता है, तो भेजने का अनुरोध EmailTemplateContactAmbiguous लौटाता है; फिर से प्रयास करने से पहले डुप्लिकेट रिकॉर्ड अपडेट करें।
भेजने के लिए ईमेल अनुमतियाँ लगती हैं। emails:write वाली कुंजी संपर्क खोजने की अनुमति के बिना प्रकाशित टेम्पलेट भेज सकती है। emails:read से बनने वाले संदेश की गैर-संवेदनशील सामग्री तक पहुँच मिलती है। संपर्क और प्रॉपर्टी खोजने के लिए पहले वाली अनुमतियाँ ही लागू रहती हैं।
भेजने में टेम्पलेट का प्रकाशित संस्करण इस्तेमाल होता है। ड्राफ़्ट कभी नहीं भेजे जाते। अज्ञात टेम्पलेट 404 के साथ अस्वीकार होता है, और जिस टेम्पलेट का कोई प्रकाशित संस्करण नहीं है, वह 422 के साथ।
language टेम्पलेट की भाषाओं में से एक चुनता है। टेम्पलेट की डिफ़ॉल्ट भाषा भेजने के लिए इसे छोड़ दें। अगर आप ऐसी भाषा माँगते हैं जो टेम्पलेट में नहीं है, तो टेम्पलेट की अपनी on_missing_language सेटिंग तय करती है कि उसकी जगह सबसे नज़दीकी भाषा भेजी जाए या भेजना अस्वीकार हो। जो टेम्पलेट language_source_required सेट करता है, वह ऐसे भेजने को अस्वीकार करता है जिसमें कोई भाषा नहीं बताई गई हो।
टेम्पलेट की श्रेणी डिफ़ॉल्ट है, और आपकी श्रेणी उसकी जगह लागू होती है। category छोड़ने पर भेजना टेम्पलेट की श्रेणी अपना लेता है, इसलिए ट्रांज़ैक्शनल टेम्पलेट के लिए इसे हर कॉल में दोहराने की ज़रूरत नहीं है।

ईमेल टेम्पलेट में टेम्पलेट लिखना, प्रकाशित करना और टेम्पलेट में इस्तेमाल होने वाली संरचनाएँ बताई गई हैं।

किसी प्राप्तकर्ता के लिए सामग्री पढ़ना

टेम्पलेट संदेश इतिहास उन संपर्क मानों का उपयोग करता है जो भेजना स्वीकार होते समय सहेजे गए थे, भले ही आप बाद में संपर्क बदलें या हटा दें। हर कॉपी की गई डिलीवरी की अपनी प्राप्तकर्ता ID होती है।

प्राप्तकर्ताओं की ID पाने के लिए संदेश के प्राप्तकर्ताओं की सूची लें, फिर संग्रहीत संदेश सामग्री पाएँ को recipient_id दें। एक से ज़्यादा प्राप्तकर्ता स्नैपशॉट वाला नया टेम्पलेट संदेश इस चयनकर्ता के बिना 422 लौटाता है। अकेला प्राप्तकर्ता अपने आप चुना जाता है; किसी दूसरे संदेश का प्राप्तकर्ता देने पर 404 लौटता है।

संदेश की GET और सूची प्रतिक्रियाएँ पहले To प्राप्तकर्ता के लिए स्वीकार किया गया विषय दिखाती हैं, जिसकी पहचान subject_recipient_id से होती है। प्राप्तकर्ताओं की सूची हर प्राप्तकर्ता का अपना विषय देती है। बॉडी संग्रहण बंद होने पर भी ये विषय उपलब्ध रहते हैं। सामग्री पढ़ना फिर भी संदेश की संग्रहण और रिटेंशन सेटिंग का पालन करता है: संग्रहीत न होने पर 404, लंबित रहने पर 425, और अवधि खत्म होने के बाद 410।

अगर रखा गया प्राप्तकर्ता स्नैपशॉट उपलब्ध न रहे, तो संदेश की स्थिति और प्रतिनिधि विषय पढ़े जा सकते हैं, लेकिन प्राप्तकर्ताओं के विषय छोड़ दिए जाते हैं और सामग्री उपलब्ध नहीं होती। पहले के भेजे गए संदेश को दोबारा बनाने के लिए रीड संपर्क के मौजूदा मान नहीं खोजते।

टैग और मेटाडेटा में अंतर

ये किसी भेजे गए ईमेल के साथ आपका अपना डेटा जोड़ते हैं, और उनमें अंतर यह है कि आप बाद में उस डेटा को कैसे खोजते हैं:

tags संरचित {name, value} जोड़े होते हैं: हर भेजने में अधिकतम 20, नाम अधिकतम 32 अक्षर, मान अधिकतम 64 अक्षर, केवल ASCII अक्षर, अंक, अंडरस्कोर और हाइफ़न, और भेजने के भीतर नाम अद्वितीय। टैग फ़िल्टर आयाम हैं, इसलिए आप संदेश सूची को टैग से फ़िल्टर कर सकते हैं और एनालिटिक्स व डैशबोर्ड सारांश को टैग के अनुसार बाँट सकते हैं। इन्हें कम विविधता वाले लेबल के लिए इस्तेमाल करें, जैसे campaign, experiment_variant या source।
metadata एक मनचाहा JSON ऑब्जेक्ट है, सीरियलाइज़ होने पर अधिकतम 2 KB। हम इसे सहेजते हैं, API रीड में लौटाते हैं और हर वेबहुक इवेंट में वापस भेजते हैं, इसलिए यह उस संदर्भ के लिए उपयुक्त है जो आप वापस पाना चाहते हैं: आंतरिक ID, फ़ॉरेन कुंजियाँ, संरचित पेलोड।
reference 1 से 255 अक्षरों की एक स्ट्रिंग है जिससे आप संदेश खोजना चाहते हैं, जैसे ऑर्डर या टिकट नंबर। GET /v1/email/messages?reference= इसे सटीक रूप से और अक्षरों के छोटे-बड़े रूप का ध्यान रखते हुए मिलाता है, और कई संदेशों में एक ही मान हो सकता है। यह रीड में लौटाया जाता है और संदेश के वेबहुक इवेंट में वापस भेजा जाता है। इसे केवल तब सेट करें जब आपको इससे खोजना हो, और बाकी कोई भी डेटा metadata में रखें।

हर वेबहुक इवेंट में टैग और मेटाडेटा के साथ सहसंबंध ID (email_id, recipient_id) भी शामिल होते हैं, इसलिए आप दूसरी खोज किए बिना अपने रिकॉर्ड से मिलान कर सकते हैं। __bird से शुरू होने वाले टैग नाम और शीर्ष-स्तरीय मेटाडेटा कुंजियाँ अस्वीकार की जाती हैं। आपको डिवाइस, भौगोलिक क्षेत्र, मेलबॉक्स प्रदाता, बाउंस प्रकार या प्राप्तकर्ता डोमेन को किसी भी फ़ील्ड में डालने की ज़रूरत नहीं है, क्योंकि हम इनमें से हर एक को पहले से एनालिटिक्स आयाम के रूप में दर्ज करते हैं।

कोड उदाहरण

{
  "tags": [{ "name": "campaign", "value": "onboarding" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" },
  "reference": "ord_98765"
}

अटैचमेंट

attachments हर संदेश में अधिकतम 20 फ़ाइलें लेता है, base64 में एन्कोड किए गए बाइट के रूप में इनलाइन। अगर base64 एन्कोडिंग के बाद संदेश का अनुमानित आकार 20 MB से ज़्यादा होता है, तो हम भेजना अस्वीकार कर देते हैं, इसलिए गुंजाइश रखने के लिए अटैचमेंट की मूल सामग्री 15 MB या उससे कम रखें। अटैचमेंट में फ़ील्ड की शर्तें, इनलाइन इमेज, अवरुद्ध फ़ाइल प्रकार और अटैचमेंट वापस डाउनलोड करने का तरीका दिया गया है।

202 का क्या अर्थ है

सफल भेजने पर 202 Accepted लौटता है, जिसमें em_ उपसर्ग वाली संदेश ID और status: accepted होते हैं:

कोड उदाहरण

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "hello@yourdomain.com" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

202 का अर्थ है कि हमने भेजने का अनुरोध स्थायी रूप से स्वीकार कर लिया है। जिन विफलताओं को आप ठीक कर सकते हैं, वे उसी अनुरोध पर 422 के रूप में लौटती हैं: असत्यापित प्रेषक डोमेन, या ऐसा फ़ील्ड जो सत्यापन में विफल हो। हर प्राप्तकर्ता का परिणाम (डिलीवर हुआ, बाउंस हुआ, स्थगित हुआ, शिकायत हुई) बाद में वेबहुक और संदेश पढ़ने वाले एंडपॉइंट के ज़रिए आता है।

इससे दो बातें निकलती हैं:

पढ़ने पर स्थिति मिलती है, बॉडी नहीं। GET /v1/email/messages/{message_id} संदेश और प्राप्तकर्ता की स्थिति लौटाता है, कभी भी html या text बॉडी नहीं। जब वर्कस्पेस के लिए सामग्री संग्रहण चालू हो, तो संग्रहीत बॉडी GET /v1/email/messages/{message_id}/content से अधिकतम 30 दिनों तक उपलब्ध रहती हैं।
पढ़ने का परिणाम कुछ देर भेजने से पीछे रह सकता है। 202 के तुरंत बाद पढ़ने वाले एंडपॉइंट पर 404 का अर्थ है कि संदेश अभी दिखाई नहीं दे रहा, इसलिए थोड़ी देर में फिर से प्रयास करें।

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

हर तार्किक भेजने के लिए एक अद्वितीय मान के साथ Idempotency-Key हेडर भेजें। अगर अनुरोध सफल हुआ लेकिन आपको प्रतिक्रिया नहीं मिली, तो उसी कुंजी के साथ उसे दोबारा भेजें। API दूसरा ईमेल भेजने के बजाय मूल परिणाम लौटाता है और उसमें Idempotency-Replay हेडर शामिल करता है। Idempotency में कुंजी का प्रारूप और उसके संग्रहण की अवधि दी गई है।

बैच में भेजना

API अनुरोधों की संख्या घटाने के लिए, POST /v1/email/batches अधिकतम 100 स्वतंत्र संदेश स्वीकार करता है और उन्हें एक इकाई के रूप में सत्यापित करता है। एकल-भेजने वाले एंडपॉइंट को लूप में कॉल करना भी समर्थित है। बैच का हर आइटम इसी पेज वाला पेलोड इस्तेमाल करता है, scheduled_at सहित, इसलिए एक बैच में तुरंत और शेड्यूल किए गए संदेश दोनों हो सकते हैं।

लागत और बिलिंग

ईमेल भेजने की गिनती हर प्राप्तकर्ता के हिसाब से होती है, इसलिए तीन प्राप्तकर्ताओं वाला संदेश तीन भेजने के बराबर गिना जाता है। Email Free प्लान पर भेजे गए ईमेल उसके मासिक और दैनिक कोटे में गिने जाते हैं। सशुल्क Email प्लान पर हर भेजने का शुल्क प्लान की प्रति 1,000 ईमेल दर पर आपके वॉलेट से लिया जाता है। बिलिंग और उपयोग में गिनती का मॉडल और मौजूदा उपयोग पढ़ने का तरीका दिया गया है, और ईमेल मूल्य पेज पर हर प्लान की दर दी गई है।

अगले कदम

ईमेल टेम्पलेट: वे टेम्पलेट बनाएँ और प्रकाशित करें जिन्हें आप यहाँ भेजते हैं
श्रेणियाँ: marketing और transactional सप्रेशन के व्यवहार को कैसे बदलते हैं
सप्रेशन: हम किन्हें डिलीवर नहीं करते, और क्यों
शेड्यूल की गई भेजाई: scheduled_at के साथ भविष्य के किसी समय पर डिलीवर करें
टेस्टिंग सैंडबॉक्स: सैंडबॉक्स प्राप्तकर्ता और डोमेन सत्यापन से पहले भेजना
API संदर्भ: अनुरोध और प्रतिक्रिया के पूरे स्कीमा

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

अभ्यास करें और इम्प्लीमेंटेशन ब्रीफ़ पाएँ

संबंधित संसाधन