ईमेल इवेंट

हर प्राप्तकर्ता जैसे-जैसे डिलीवरी के चरणों से गुज़रता है, हम इवेंट भेजते हैं। तीन पतों पर एक बार भेजने से तीन स्वतंत्र स्ट्रीम बनती हैं, जिन्हें email_id और recipient_id से आपस में जोड़ा जाता है। यह पेज ईमेल इवेंट के प्रकार परिभाषित करता है। सिग्नेचर, फिर से प्रयास, क्रम और रीप्ले के लिए वेबहुक देखें।

हर प्राप्तकर्ता email.accepted से शुरू होता है, फिर email.processed पर जाता है। ब्रॉडकास्ट का हर प्राप्तकर्ता एक अलग संदेश होता है, इसलिए उसे भी अपना email.accepted मिलता है, लेकिन यह वेबहुक के रूप में नहीं, बल्कि केवल इवेंट API और ईमेल लॉग में मिलता है। इसके बाद संदेश या तो प्राप्त करने वाला सर्वर स्वीकार करता है (email.delivered), या वह स्थगित होकर फिर से भेजा जाता है (email.deferred, जो अंत में delivered या bounced बनता है), या प्राप्त करने वाला सर्वर उसे अस्वीकार कर देता है (email.bounced), या उसकी डिलीवरी का कोई प्रयास होता ही नहीं (email.rejected)। डिलीवरी के बाद स्ट्रीम में email.out_of_band_bounce, email.complained, email.opened, email.clicked, email.unsubscribed और email.list_unsubscribed आ सकते हैं।

हर प्राप्तकर्ता ठीक एक अंतिम स्थिति पर पहुँचता है: delivered, bounced, complained या rejected। यह स्थिति GET /v1/email/messages/{message_id}/recipients से हर प्राप्तकर्ता के status के रूप में लौटती है। एंगेजमेंट इवेंट इसे कभी नहीं बदलते: जिस प्राप्तकर्ता ने संदेश खोला, वह फिर भी delivered ही रहता है। देर से आई बाउंस रिपोर्ट इसे बदल देती है, क्योंकि प्राप्त करने वाला सर्वर पहले दी गई स्वीकृति वापस ले रहा होता है। इसलिए प्राप्तकर्ता delivered से bounced पर चला जाता है। पूरे संदेश की अपनी समेकित स्थिति और हर स्थिति की गिनती GET /v1/email/messages/{message_id} पर मिलती है।

इवेंट का ढाँचा

इवेंट उसी तीन फ़ील्ड वाले ढाँचे में आते हैं जिसका उपयोग हर वेबहुक करता है: type, timestamp (इवेंट कब हुआ, RFC 3339 में), और प्रकार के अनुसार एक data ऑब्जेक्ट।

{
  "type": "email.delivered",
  "timestamp": "2026-07-23T14:51:47.107Z",
  "data": {
    "email_id": "em_01ky7qc398fmxraqtxn604zeq9",
    "recipient_id": "er_01ky7qc398fmwsc96nt6anrbqs",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "delivered@messagebird.dev",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

हर आउटबाउंड इवेंट में email_id, recipient_id, workspace_id, recipient पता और उसका ढाँचा-स्तर का recipient_role (to, cc या bcc) शामिल होता है। इसमें भेजने के अनुरोध से tags और metadata भी वापस आते हैं, ताकि आप इवेंट को अपने रिकॉर्ड से मिला सकें। जब भेजे गए संदेश में कोई वैकल्पिक मान नहीं था, तो वह मान null होता है, और यह broadcast_id पर भी लागू है। यह फ़ील्ड बताता है कि संदेश किस ब्रॉडकास्ट के हिस्से के रूप में भेजा गया, ताकि आप हर संदेश को अलग से खोजे बिना किसी ब्रॉडकास्ट के इवेंट समूहित कर सकें। जिस संदेश के पीछे कोई ब्रॉडकास्ट नहीं है, उस पर यह null होता है। एक स्थिति में ब्रॉडकास्ट होने पर भी null आता है: इस फ़ील्ड के जुड़ने से पहले भेजे गए मेल की अनसब्सक्राइब लिंक में किसी ब्रॉडकास्ट का नाम नहीं होता। इसलिए ऐसी लिंक से हुआ ऑप्ट-आउट email.unsubscribed और email.list_unsubscribed पर null दिखाता है, चाहे मेल किसी ब्रॉडकास्ट ने भेजा हो या नहीं। इन दो इवेंट पर null को अनिर्णायक मानें, वरना आप किसी ब्रॉडकास्ट के ऑप्ट-आउट कम गिनेंगे। broadcast_id आपको केवल वेबहुक पर मिलता है: नीचे दिया गया इवेंट API हर इवेंट को इसके बिना लौटाता है। इवेंट के प्रकार अतिरिक्त फ़ील्ड जोड़ते हैं, जिनका विवरण लाइफ़साइकल, एंगेजमेंट, सप्रेशन और इनबाउंड अनुभागों में है।

यही इवेंट बाद में GET /v1/email/messages/{message_id}/events से क्वेरी किए जा सकते हैं, जहाँ हर इवेंट का एक id (ev_ उपसर्ग) और एक occurred_at भी होता है। इसका उपयोग छूटा डेटा भरने, रीप्ले करने या आपके एंडपॉइंट को मिले इवेंट से मिलान करने के लिए करें। कुछ फ़ील्ड आपको वेबहुक से नहीं, केवल उसी API से मिलते हैं; संबंधित इवेंट का विवरण हर ऐसे फ़ील्ड को बताता है।

लाइफ़साइकल इवेंट

email.accepted

हमने भेजने का अनुरोध स्वीकार कर लिया है और डिलीवरी की तैयारी शुरू कर दी है। यह हर अनुरोधित प्राप्तकर्ता के लिए एक बार फ़ायर होता है और उस स्ट्रीम का पहला इवेंट होता है। ब्रॉडकास्ट के प्राप्तकर्ता को भी यह मिलता है, क्योंकि हर प्राप्तकर्ता अपना अलग संदेश है, लेकिन इसे डिलीवर नहीं किया जाता, केवल दर्ज किया जाता है: इसे अपने webhook एंडपॉइंट से नहीं, बल्कि इवेंट्स API या ईमेल लॉग से पढ़ें। पेलोड: केवल पहचान वाला आधार।

email.processed

संदेश तैयार हो गया है और प्राप्तकर्ता के मेल सर्वर पर डिलीवरी के लिए कतार में है। पेलोड: webhook पर केवल पहचान वाला आधार; इवेंट्स API इसमें mailbox_provider और mailbox_provider_region जोड़ता है, जो प्राप्त करने वाले मेल सिस्टम का वर्गीकरण है (उदाहरण के लिए gmail, NA)। यह तब मौजूद होता है जब इसे निर्धारित किया जा सका हो, अन्यथा null होता है। इस इवेंट के timestamp की तुलना email.accepted के समय से करने पर आपको किसी एक सेंड पर हमारा अपना प्रोसेसिंग समय मिलता है। ब्रॉडकास्ट में ऐसा कोई अंतराल नहीं होता: उसकी स्वीकृति और प्रोसेसिंग का डिस्पैच समय एक ही होता है, इसलिए दोनों टाइमस्टैम्प किसी प्रोसेसिंग अवधि को दर्शाने के बजाय एक जैसे होते हैं। स्वीकृति आप तक केवल इवेंट्स API के ज़रिए occurred_at के रूप में पहुँचती है।

email.delivered

प्राप्त करने वाले मेल सर्वर ने संदेश स्वीकार किया और उसकी ज़िम्मेदारी ले ली। इस इवेंट से यह तय नहीं होता कि संदेश इनबॉक्स में पहुँचा या पढ़ा गया। Inbox Insights सैंपल के आधार पर प्लेसमेंट का अनुमान देता है; ओपन और क्लिक इवेंट ट्रैकिंग अनुरोध दर्ज करते हैं। पेलोड: webhook पर केवल पहचान वाला आधार; इवेंट्स API इसमें sending_ip जोड़ता है, यानी वह पता जिससे संदेश भेजा गया था। यह तब काम आता है जब डिलीवरेबिलिटी की कोई समस्या किसी एक IP से जुड़ी हो। साथ में mailbox_provider और mailbox_provider_region भी जुड़ते हैं।

email.deferred

एक अस्थायी विफलता: प्राप्त करने वाले सर्वर ने हमसे बाद में फिर से प्रयास करने को कहा (मेलबॉक्स भरा होना, ग्रेलिस्टिंग, अनुरोध दर सीमित करना)। हम अपने आप फिर से प्रयास करते हैं, और अंत में प्राप्तकर्ता की स्थिति email.delivered या email.bounced हो जाती है। इसलिए यह इवेंट अंतिम नहीं, केवल सूचना के लिए है, और उससे पहले प्राप्तकर्ता कई बार डेफ़र हो सकता है। पेलोड: webhook पर bounce_type, bounce_class, defer_reason (सर्वर द्वारा बताया गया कारण) और sending_ip; इवेंट्स API इसमें mailbox_provider और mailbox_provider_region जोड़ता है।

विफलता इवेंट

email.bounced

SMTP के समय एक स्थायी विफलता: प्राप्त करने वाले सर्वर ने संदेश अस्वीकार कर दिया, और प्राप्तकर्ता की अंतिम स्थिति bounced हो जाती है। पेलोड: webhook पर bounce_type (वर्गीकरण तालिका देखें), bounce_class, bounce_code (SMTP रिप्लाई कोड, उदाहरण के लिए 550), bounce_description (सर्वर द्वारा बताया गया कारण) और sending_ip; इवेंट्स API इसमें mailbox_provider और mailbox_provider_region जोड़ता है। हार्ड बाउंस होने पर पता सप्रेस किया जाता है।

email.out_of_band_bounce

एक देर से आया बाउंस: प्राप्त करने वाले सर्वर ने SMTP के समय संदेश स्वीकार किया और उसके बाद बाउंस रिपोर्ट भेजी। इसका वर्गीकरण email.bounced जैसा ही है (webhook पर bounce_type, bounce_class, bounce_code, bounce_description, sending_ip; इवेंट्स API से mailbox_provider और mailbox_provider_region)। जब रिपोर्ट बाउंस के रूप में वर्गीकृत होती है (तालिका की कोई भी क्लास), तो सर्वर अपनी पिछली स्वीकृति वापस ले चुका होता है, इसलिए प्राप्तकर्ता की स्थिति delivered से बदलकर bounced हो जाती है। जिन रिपोर्टों की क्लास तालिका में नहीं है, जैसे ऑटो-रिप्लाई, वे टाइमलाइन पर दर्ज होती हैं और स्थिति नहीं बदलतीं। हार्ड आउट-ऑफ़-बैंड बाउंस भी पते को सप्रेस करता है।

email.rejected

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

अस्वीकृति से पहले प्राप्त करने वाले मेल सिस्टम का वर्गीकरण हो पाने पर इवेंट्स API mailbox_provider और mailbox_provider_region भी जोड़ता है।

email.complained

प्राप्तकर्ता ने संदेश को स्पैम चिह्नित किया और मेलबॉक्स प्रदाता ने अपने फ़ीडबैक लूप के ज़रिए इसकी सूचना वापस भेजी। शिकायतें डिलीवरी के बाद आती हैं और अंतिम स्थिति को complained कर देती हैं। पेलोड: feedback_type, यानी प्रदाता द्वारा भेजी गई रिपोर्ट का प्रकार, जैसे abuse या fraud, और प्रदाता के न बताने पर null, साथ ही इवेंट्स API से mailbox_provider और mailbox_provider_region। शिकायत मार्केटिंग मेल के लिए पते को सप्रेस करती है। अपनी शिकायत दर कम रखें, क्योंकि प्रदाता रिपोर्ट पाने वाले प्रेषकों की भेजने की गति धीमी कर देते हैं।

एंगेजमेंट इवेंट

email.opened

संदेश के मुख्य भाग में ट्रैकिंग पिक्सेल लोड हुआ। पेलोड: ज्ञात होने पर ip_address और user_agent; इवेंट्स API is_prefetched, country (ISO 3166-1 alpha-2, क्लाइंट IP से निकाला गया), mailbox_provider और mailbox_provider_region जोड़ता है। किसी ओपन को गिनने से पहले is_prefetched जाँचें। जब किसी व्यक्ति के संदेश खोलने के बजाय इनबॉक्स की गोपनीयता सुविधा ने पिक्सेल अपने-आप लोड किया हो, तो यह true होता है, और ऐसे ओपन गिनने से आपकी ओपन दर बढ़ी हुई दिखती है। ओपन और क्लिक ट्रैकिंग में इसकी व्यवस्था का विवरण है।

email.clicked

प्राप्तकर्ता ने ट्रैक किए गए लिंक पर क्लिक किया। पेलोड: url (क्लिक किया गया लिंक), तथा ज्ञात होने पर ip_address और user_agent; इवेंट API इसमें country, mailbox_provider और mailbox_provider_region जोड़ता है। क्लिक आम तौर पर ओपन की तुलना में जुड़ाव का अधिक मज़बूत संकेत होते हैं, क्योंकि प्राइवेसी प्रॉक्सी ट्रैकिंग पिक्सेल अपने-आप लोड कर सकते हैं।

email.unsubscribed

प्राप्तकर्ता ने मैसेज के मुख्य भाग में दिए अनसब्सक्राइब लिंक का उपयोग किया। पेलोड: वेबहुक पर केवल पहचान आधार; इवेंट API इसमें mailbox_provider और mailbox_provider_region जोड़ता है। यह इवेंट ऑप्ट-आउट प्राथमिकता दर्ज करता है, जो मार्केटिंग मेल को रोकती है। लिंक आपके मेल में कैसे जुड़ता है, यह अनसब्सक्राइब लिंक में बताया गया है।

email.list_unsubscribed

प्राप्तकर्ता ने वह वन-क्लिक अनसब्सक्राइब बटन इस्तेमाल किया, जिसे मेलबॉक्स प्रदाता अपने UI में मैसेज के List-Unsubscribe हेडर के आधार पर दिखाता है। पेलोड: वेबहुक पर केवल पहचान आधार (साथ में इवेंट API से mailbox_provider और mailbox_provider_region); तरीका इवेंट टाइप से ही पता चलता है, इसीलिए यह email.unsubscribed से अलग है। यह भी ऑप्ट-आउट प्राथमिकता दर्ज करता है, जो मार्केटिंग मेल को रोकती है।

मैसेज-स्तर के इवेंट

दो इवेंट किसी एक प्राप्तकर्ता के बजाय पूरे मैसेज का वर्णन करते हैं, इसलिए उनके data में email_id, workspace_id, tags और metadata होते हैं, पर प्राप्तकर्ता की पहचान नहीं होती। दोनों शेड्यूल की गई सेंडिंग से जुड़े हैं।

email.scheduled

हमने भविष्य के scheduled_at वाला सेंड स्वीकार किया। पेलोड: मैसेज-स्तर का आधार और scheduled_at। वह समय आने पर हर प्राप्तकर्ता का लाइफ़साइकल email.accepted से शुरू होता है।

email.canceled

शेड्यूल किया गया मैसेज भेजे जाने से पहले रद्द कर दिया गया, इसलिए उससे प्राप्तकर्ता लाइफ़साइकल का कोई इवेंट नहीं बनता। पेलोड: केवल मैसेज-स्तर का आधार।

इनबाउंड और मेलबॉक्स इवेंट

email.received आने वाले मेल के लिए है। यह तब फ़ायर होता है जब हम कोई इनबाउंड संदेश प्राप्त करके पार्स करते हैं। इसके पेलोड में inbound_message_id, पते, विषय और प्रमाणीकरण के नतीजे शामिल होते हैं। सेटअप, पेलोड और वापस प्राप्त करने वाला API ईमेल प्राप्त करना में दिए गए हैं। इसके अलावा, मेलबॉक्स का अपना email_mailbox.* परिवार है, जिसका विवरण मेलबॉक्स गाइड में है।

बाउंस वर्गीकरण

bounce_class संख्यात्मक बाउंस वर्गीकरण है, जो email.bounced, email.out_of_band_bounce और email.deferred में शामिल होता है। यह मोटे bounce_type में समाहित होता है और बारीक कोड भी बनाए रखता है। इसलिए दोनों के soft के रूप में रिपोर्ट होने पर भी आप भरे हुए मेलबॉक्स और रूटिंग विफलता में अंतर कर सकते हैं:

इस सूची से बाहर की कोई भी श्रेणी undetermined पर मैप होती है। केवल hard बाउंस ही पते को सप्रेस करते हैं; soft, block, admin और undetermined ऐसा नहीं करते, क्योंकि उस पते पर मेल अब भी डिलीवर हो सकता है।

स्वचालित सप्रेशन

दो इवेंट किसी प्राप्तकर्ता को वर्कस्पेस की सप्रेशन सूची में अपने-आप जोड़ते हैं, और दोनों अलग-अलग मेल रोकते हैं:

हार्ड बाउंस सब कुछ रोकता है, क्योंकि वह पता ही अब मौजूद नहीं है। शिकायत केवल मार्केटिंग मेल रोकती है, क्योंकि जिस व्यक्ति ने आपके न्यूज़लेटर को स्पैम बताया, उसे भी अपना पासवर्ड रीसेट करना पड़ता है।

email.unsubscribed और email.list_unsubscribed शिकायत की तरह ही केवल मार्केटिंग मेल रोकते हैं, लेकिन एक अलग रिकॉर्ड के ज़रिए: सप्रेशन जोड़ने के बजाय वे प्राप्तकर्ता के ऑप्ट-आउट को एक बताई गई प्राथमिकता के रूप में दर्ज करते हैं। ऑप्ट-आउट क्या करता है में उस रिकॉर्ड का पूरा विवरण है।

हर बार कोई प्रविष्टि जुड़ने पर एक email_suppression.created इवेंट भेजा जाता है, जिसमें suppression_id, सप्रेस किया गया email, reason और workspace_id होते हैं। पूरा रिकॉर्ड स्कीमा और प्रविष्टियों को मैन्युअल रूप से प्रबंधित करने का तरीका सप्रेशन गाइड में है।

सप्रेस किए गए पते पर बाद में भेजे गए संदेश शुरुआत में ही rejection_reason: "recipient_suppressed" के साथ email.rejected के रूप में अस्वीकार कर दिए जाते हैं, और ये आपकी डिलीवरेबिलिटी पर कभी असर नहीं डालते।

अगले कदम

• वेबहुक और इवेंट: एंडपॉइंट सेटअप, सिग्नेचर सत्यापन, फिर से प्रयास और रीप्ले
• सप्रेशन: सप्रेशन सूची कैसे काम करती है और उसे कैसे प्रबंधित करें
• अनसब्सक्राइब लिंक: email.unsubscribed और email.list_unsubscribed के पीछे के पाथ कैसे जोड़ें
• टेस्टिंग और सैंडबॉक्स: सैंडबॉक्स से भेजे गए संदेश सामान्य पाथ से असली इवेंट भेजते हैं, और अपने हैंडलर को परखने का यही सबसे सस्ता तरीका है
• Webhooks सही तरीके से: विश्वसनीय डिलीवरी इवेंट्स: एक वीडियो, जिसमें एक वेबहुक बनाया जाता है और इवेंट आते हुए देखे जाते हैं