ईमेल आँकड़े API

ईमेल आँकड़े API वे समेकित आँकड़े लौटाता है जो Metrics डैशबोर्ड पर दिखते हैं, साथ ही उनसे गणना किया गया भेजने की स्थिति का निर्णय भी। इसका उपयोग डैशबोर्ड बनाने, डेटा निर्यात करने या ईमेल की स्थिति की निगरानी के लिए करें। अनुरोधों के लिए emails स्कोप पर पढ़ने की अनुमति चाहिए।

संयुक्त फ़िल्टर, चुने गए मेट्रिक और प्रति समूह पूरी समय श्रृंखला वाली रिपोर्टों के लिए लचीले क्वेरी एंडपॉइंट का उपयोग करें। किसी असिस्टेंट के ज़रिए इन रिपोर्टों को देखने के लिए AI से ईमेल एनालिटिक्स क्वेरी करें देखें।

टाइप किए गए मेथड TypeScript, Python, PHP और Go SDK में email.stats और email.health के अंतर्गत उपलब्ध हैं। bird CLI इन्हें bird email stats और bird email health के रूप में उपलब्ध कराता है, और कोई एजेंट इन तक email_stats_* और email_health MCP टूल के ज़रिए पहुँचता है। पूरे अनुरोध और प्रतिक्रिया स्कीमा API संदर्भ में हैं।

समेकित आँकड़ा और समय श्रृंखला

डैशबोर्ड के ऊपरी हिस्से को तीन एंडपॉइंट कवर करते हैं:

• GET /v1/email/stats/summary पूरी अवधि के लिए एक समेकित पंक्ति लौटाता है। इसमें accepted, delivered, bounced, complained, opened, clicked और उनके उप-प्रकारों की लाइफ़साइकिल गिनतियाँ शामिल हैं। इसमें व्युत्पन्न delivery_rate, bounce_rate, complaint_rate, open_rate और click_rate भी शामिल हैं। प्रोसेसिंग, डिलीवरी और कुल विलंब के पर्सेंटाइल p50, p95 और p99 को कवर करते हैं। compare=previous_period पास करने पर प्रतिक्रिया में उतनी ही लंबी पिछली अवधि और उससे हुआ बदलाव भी शामिल होता है।
• GET /v1/email/stats/daily और GET /v1/email/stats/hourly वही गिनतियाँ प्रति दिन या प्रति घंटा एक पंक्ति में लौटाते हैं। खाली अवधियों में शून्य वाली पंक्तियाँ भरी जाती हैं, ताकि चार्ट में कभी कोई खाली जगह न रहे।

दरें भिन्न के रूप में लौटती हैं, इसलिए 0.9939 का delivery_rate 99.39% है। जिस दर का हर शून्य हो, वह null होती है। इसी तरह जिस अवधि में कुछ भी डिलीवर नहीं हुआ, वह 0 दिखाने के बजाय open_rate रिपोर्ट करती है। दरें श्रेय देने के लिए इवेंट समय का उपयोग करती हैं। भेजने का समय यह तय नहीं करता कि कोई इवेंट किस अवधि में गिना जाए, इसलिए किसी पुराने संदेश पर अवधि के दौरान आया एंगेजमेंट भी शामिल होता है। जब एंगेजमेंट और डिलीवरी अलग-अलग अवधियों में पड़ते हैं, तो ओपन और क्लिक दरें 1 से अधिक हो सकती हैं। हर दर का सटीक सूत्र, जिसमें यह भी शामिल है कि देर से आया आउट-ऑफ़-बैंड बाउंस प्रभावी डिलीवरी को कैसे बदलता है, सारांश संदर्भ में हर फ़ील्ड के साथ दिया गया है।

सारांश, दैनिक और प्रति घंटा प्रतिक्रियाएँ अवधि को दोहराती हैं और data_as_of शामिल करती हैं, जो उपलब्ध होने पर अंतिम सफल समेकन रीफ़्रेश का समय है। यह null हो सकता है, और टाइमस्टैम्प होने से यह पक्का नहीं होता कि सभी इवेंट आ चुके हैं। लचीला क्वेरी एंडपॉइंट हमेशा data_as_of: null लौटाता है। उपलब्ध रीफ़्रेश टाइमस्टैम्प को अपने डैशबोर्ड पर दिखाएँ, लेकिन उसे पूरे डेटा के प्रमाण के रूप में प्रस्तुत न करें।

विंडो चुनना

from और to में आप या तो कैलेंडर दिन (YYYY-MM-DD) या RFC 3339 इंस्टेंट दे सकते हैं, और कौन-से रूप स्वीकार होते हैं, यह हर एंडपॉइंट के लिए अलग है:

इंस्टेंट सीमाएँ घंटे के स्तर पर होती हैं, इसलिए रोलिंग "last 24 hours" एक ही अनुरोध में मिल जाता है। /summary पर दिन और इंस्टेंट को मिलाने से 422 मिलता है।

timezone को America/New_York जैसे किसी IANA पहचानकर्ता पर सेट करें, ताकि दिन और घंटे की सीमाएँ UTC के बजाय उसी ज़ोन में गणना हों। from और to छोड़ने पर लागू होने वाले डिफ़ॉल्ट भी उसी ज़ोन में गणना होते हैं। जब timezone सेट हो, तब from और to में अपना कोई UTC ऑफ़सेट नहीं होना चाहिए।

ब्रेकडाउन

13 ब्रेकडाउन एंडपॉइंट डिलीवरी और एंगेजमेंट की उन्हीं संख्याओं को एक आयाम के अनुसार बाँटते हैं:

• भेजने वाले: /sending-domains, /sending-ips और /recipient-domains (वह मेलबॉक्स डोमेन जिस पर आपने भेजा)।
• ईमेल कहाँ पहुँचा: /mailbox-providers (Gmail, Outlook आदि) और /mailbox-provider-regions।
• आपने क्या भेजा: /tags (भेजते समय सेट किए गए टैग, जो सबसे लचीला विभाजन है), /categories, /templates और /broadcasts।
• एंगेजमेंट का संदर्भ: /locations (प्राप्तकर्ता का भूगोल) और /clients (वह मेल क्लाइंट जिसमें ईमेल खोला गया)।
• विफलताएँ: /bounce-codes (प्राप्त करने वाले सर्वर की प्रतिक्रिया के अनुसार समूहित) और /complaint-types।

ये सभी /v1/email/stats/ के अंतर्गत हैं। पंक्तियाँ किसी sort मेट्रिक के अनुसार घटते क्रम में आती हैं और limit (डिफ़ॉल्ट 50, अधिकतम 200) तक सीमित रहती हैं। प्रतिक्रिया में total भी होता है, यानी विंडो में आयाम के अलग-अलग मानों की संख्या। सीमित परिणाम पहचानने के लिए total की तुलना लौटाई गई पंक्तियों की संख्या से करें। जिन पंक्तियों का सॉर्ट मेट्रिक शून्य हर वाली दर है, वे सबसे अंत में आती हैं।

हर एंडपॉइंट का sort डिफ़ॉल्ट वही मेट्रिक है जिसके आधार पर रैंक करने के लिए वह एंडपॉइंट बना है:

include_trend=true हर पंक्ति में प्रति-बकेट दर की एक सीरीज़ जोड़ता है, जो स्पार्कलाइन के लिए तैयार रहती है। यह टैग, कैटेगरी, टेम्पलेट, सेंडिंग डोमेन, सेंडिंग IP, प्राप्तकर्ता डोमेन, मेलबॉक्स प्रदाता और मेलबॉक्स प्रदाता क्षेत्र वाले ब्रेकडाउन पर लागू होता है।

सारांश और टाइम-सीरीज़ एंडपॉइंट हर अनुरोध में एक डाइमेंशन फ़िल्टर भी लेते हैं। category, sending_domain, sending_ip, recipient_domain, tag या template में से एक चुनें। फ़िल्टर ब्रेकडाउन पर जाए बिना किसी एग्रीगेट को एक सेंडर या कैंपेन तक सीमित करता है। एक से अधिक फ़िल्टर भेजने पर 422 लौटता है।

भेजने की सेहत

GET /v1/email/health उस सवाल का जवाब देता है जो एग्रीगेट आप पर छोड़ देते हैं: क्या आपका भेजना किसी परेशानी की ओर बढ़ रहा है। यह विंडो के लिए एक निर्णय लौटाता है, साथ में डिलीवरी, ओपन, बाउंस और शिकायतों के सिग्नल भी। हर सिग्नल में उसकी दर और निर्णय होता है। डिलीवरी, बाउंस और शिकायत के सिग्नल में वे सीमाएँ भी होती हैं जिनसे उनका निर्णय तय होता है; ओपन दर की कोई जोखिम सीमा नहीं होती। इसी वजह से कोई स्टेटस बैज हमारे बैंड का पालन कर सकता है, बिना उनकी कॉपी आपके अपने क्लाइंट में कंपाइल किए।

{
  "period": {
    "data_as_of": null,
    "from": "2026-05-25",
    "to": "2026-06-01"
  },
  "status": "watching",
  "signals": [
    {
      "metric": "delivery_rate",
      "value": 0.995,
      "limit": null,
      "status": "healthy",
      "thresholds": {
        "direction": "below",
        "throttled": 0.984,
        "watching": 0.99
      }
    },
    {
      "metric": "open_rate",
      "value": 0.20100503,
      "limit": null,
      "status": "healthy"
    },
    {
      "metric": "bounce_rate",
      "value": 0.005,
      "limit": 0.005,
      "status": "watching",
      "thresholds": {
        "direction": "above",
        "throttled": 0.006,
        "watching": 0.004
      }
    },
    {
      "metric": "complaint_rate",
      "value": 0.00010050251,
      "limit": 0.003,
      "status": "healthy",
      "thresholds": {
        "direction": "above",
        "throttled": 0.001,
        "watching": 0.0006
      }
    }
  ]
}

हर सिग्नल को उसके metric से मिलाएँ। शीर्ष-स्तर का status डिलीवरी, बाउंस और शिकायत के निर्णयों में सबसे खराब होता है: healthy, watching या throttled। open_rate इस समेकन से बाहर रहता है, क्योंकि ऊँची ओपन दर कभी जोखिम नहीं होती, और केवल यही सिग्नल strong दिखा सकता है।

सिग्नल के दो फ़ील्ड आसानी से आपस में गड़बड़ हो जाते हैं। limit दर की संदर्भ डिलीवरेबिलिटी सीमा है, और जिन दरों की कोई सीमा नहीं है उन पर यह null होता है। thresholds वह बिंदु है जहाँ निर्णय खुद बदलता है: watching और throttled दो सीमाएँ हैं, और direction बताता है कि उनमें से जोखिम वाली तरफ़ कौन-सी है, बाउंस और शिकायत दरों के लिए above और डिलीवरी दर के लिए below। सीमाएँ एक्सक्लूसिव हैं, इसलिए जो दर ठीक किसी सीमा पर हो, उसे बेहतर स्टेटस मिलता है।

सीमाएँ रिस्पॉन्स में लौटती हैं, इसलिए आप उन हिस्सों को भी ग्रेड कर सकते हैं जिनकी गणना यह एंडपॉइंट नहीं करता: /sending-domains से अपने सेंडर रैंक करें, फिर हर पंक्ति को हेल्थ रिस्पॉन्स में लौटी बाउंस दर सीमाओं से वर्गीकृत करें। Metrics डैशबोर्ड हार्ड-बाउंस और शिकायत दरों के लिए अलग चेतावनी बैंड इस्तेमाल करता है। यह API कुल बाउंस, शिकायत और डिलीवरी दरों का आकलन करता है, इसलिए इसका निर्णय डैशबोर्ड की चेतावनी से अलग हो सकता है।

throttled निर्णय डिलीवरेबिलिटी जोखिम बताता है। यह आपका भेजना नहीं रोकता।

यहाँ विंडो ऊपर के एंडपॉइंट से अलग तरह काम करती है। from और to UTC में कैलेंडर दिन होते हैं, कोई timezone पैरामीटर नहीं है, और कोई डाइमेंशन फ़िल्टर लागू नहीं होता। दोनों छोड़ देने पर विंडो आज खत्म होती है और 7 दिन पहले शुरू होती है। अधिकतम अवधि 365 दिन है।

आँकड़ों में टेस्ट ट्रैफ़िक

सैंडबॉक्स पतों पर भेजे गए ईमेल भी उसी एग्रीगेशन से गुज़रते हैं, इसलिए टेस्ट ट्रैफ़िक यहाँ के हर एंडपॉइंट में ठीक वैसे ही दिखता है जैसे डैशबोर्ड पर।

अगले कदम

• AI से ईमेल एनालिटिक्स क्वेरी करें: MCP के ज़रिए डिलीवरी, एंगेजमेंट और विलंब रिपोर्ट के लिए उदाहरण प्रॉम्प्ट
• ईमेल मेट्रिक्स: डैशबोर्ड इन संख्याओं को कैसे दिखाता है और आपको इन पर कब कार्रवाई करनी चाहिए
• स्टैट्स सारांश संदर्भ: हर फ़ील्ड, फ़िल्टर और दर का फ़ॉर्मूला
• सेंडिंग हेल्थ संदर्भ: निर्णय, हर दर के लिए उसके संकेत और उनकी सीमाएँ
• इवेंट और वेबहुक: जब समग्र आँकड़े पर्याप्त न हों, तब हर प्राप्तकर्ता की इवेंट स्ट्रीम