ईमेल इवेंट

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

हर प्राप्तकर्ता email.accepted से शुरू होता है, फिर email.processed। एक ब्रॉडकास्ट प्राप्तकर्ता अपना अलग मैसेज होता है, इसलिए उसे अपना email.accepted भी मिलता है, लेकिन केवल इवेंट API और ईमेल लॉग में, webhook के रूप में नहीं। वहाँ से मैसेज प्राप्तकर्ता सर्वर द्वारा स्वीकार किया जाता है (email.delivered), deferred और फिर से प्रयास किया जाता है (email.deferred, जो delivered या bounced में resolve होता है), प्राप्तकर्ता सर्वर द्वारा अस्वीकार किया जाता है (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} पर होता है।

इवेंट उसी तीन-फ़ील्ड एनवेलप में आते हैं जो हर webhook उपयोग करता है: 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) शामिल होता है। यह send अनुरोध से tags और metadata भी echo करता है ताकि आप इवेंट को अपने रिकॉर्ड से सहसंबद्ध कर सकें। जब send में कोई वैकल्पिक मान नहीं था तो प्रत्येक वैकल्पिक मान null होता है, broadcast_id सहित: यह उस ब्रॉडकास्ट का नाम बताता है जिसके हिस्से के रूप में send गया, ताकि आप हर send को अलग से देखे बिना ब्रॉडकास्ट के इवेंट ग्रुप कर सकें, और बिना ब्रॉडकास्ट वाले send पर यह null होता है। एक मामले में यह ऐसे send के लिए null रिपोर्ट करता है जिसमें ब्रॉडकास्ट था: हमने फ़ील्ड जोड़ने से पहले भेजे गए मेल के अनसब्सक्राइब लिंक में कोई ब्रॉडकास्ट नाम नहीं होता, इसलिए ऐसे लिंक के ज़रिए ऑप्ट-आउट email.unsubscribed और email.list_unsubscribed पर null रिपोर्ट करता है, चाहे ब्रॉडकास्ट ने मेल भेजा हो या नहीं। उन दो इवेंट पर null को अनिर्णायक मानें, वरना आप ब्रॉडकास्ट के ऑप्ट-आउट कम गिनेंगे। broadcast_id आपको केवल webhook पर मिलता है: नीचे इवेंट API हर इवेंट इसके बिना लौटाता है। इवेंट प्रकार लाइफ़साइकल, एंगेजमेंट, सप्रेशन, और इनबाउंड सेक्शन में वर्णित फ़ील्ड जोड़ते हैं।

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

email.received इनकमिंग मेल कवर करता है। यह तब fire होता है जब हम एक इनबाउंड मैसेज प्राप्त और पार्स करते हैं। इसके पेलोड में 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 इवेंट fire करता है जिसमें suppression_id, सप्रेस किया गया email, reason, और workspace_id होता है। पूरा रिकॉर्ड स्कीमा और प्रविष्टियों को मैन्युअल रूप से प्रबंधित करने का तरीका सप्रेशन गाइड में है।

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