ईमेल stats API

Email stats API वे एग्रीगेट लौटाता है जो Metrics डैशबोर्ड पर दिखाई देते हैं, साथ ही उनसे गणना किया गया सेंडिंग-हेल्थ निर्णय भी। इसका उपयोग डैशबोर्ड बनाने, डेटा एक्सपोर्ट करने, या ईमेल हेल्थ मॉनिटर करने के लिए करें। इनके लिए emails स्कोप पर रीड ऐक्सेस वाली API कुंजी आवश्यक है।

टाइप्ड मेथड 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 और 1 के बीच एक अंश के रूप में लौटता है, इसलिए 0.9939 का delivery_rate 99.39% है। जिस रेट का हर शून्य है वह null होता है, इसी तरह कोई भी अवधि जिसमें कुछ डिलीवर नहीं हुआ वह 0 पढ़ने के बजाय open_rate रिपोर्ट करती है। रेट एट्रिब्यूशन के लिए इवेंट समय का उपयोग करते हैं। भेजने का समय इस पर प्रभाव नहीं डालता कि कोई इवेंट किस विंडो में शामिल होगा, इसलिए विंडो के दौरान किसी पुराने संदेश के लिए आई सहभागिता शामिल की जाती है। प्रत्येक के पीछे का सटीक फ़ॉर्मूला, जिसमें देर से आने वाला out-of-band बाउंस प्राप्तकर्ता को डिलीवर्ड गणना से कैसे हटाता है, summary रेफ़रेंस पर प्रति फ़ील्ड प्रलेखित है।

हर रिस्पॉन्स उस विंडो को दोहराता है जिसके विरुद्ध गणना हुई, साथ ही data_as_of: वह क्षण जब तक के आँकड़े मौजूदा हैं। एग्रीगेशन हर कुछ सेकंड में रिफ़्रेश होता है, इसलिए रिस्पॉन्स लाइव के बजाय निकट-वास्तविक-समय होता है। अपने डैशबोर्ड पर संख्याओं को सेकंड-सटीक दिखाने के बजाय data_as_of का लेबल लगाएँ।

विंडो चुनना

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

एंडपॉइंट	सीमाएँ	अधिकतम विंडो
/summary	दोनों दिन, या दोनों इंस्टेंट	365 दिन, या इंस्टेंट पर 720 घंटे
/daily	कैलेंडर दिन	365 दिन
/hourly	RFC 3339 इंस्टेंट	720 घंटे (30 दिन)

इंस्टेंट सीमाएँ घंटे-ग्रेन हैं, इसी कारण रोलिंग "last 24 hours" एक ही रिक्वेस्ट में संभव है। /summary पर दिन और इंस्टेंट मिलाने पर 422 लौटता है।

timezone को एक IANA पहचानकर्ता जैसे America/New_York पर सेट करें ताकि दिन और घंटे की सीमाएँ, और from तथा to छोड़ने पर उपयोग होने वाले डिफ़ॉल्ट, UTC के बजाय उस ज़ोन में गणना हों। जब 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 डिफ़ॉल्ट वह मेट्रिक है जिसके अनुसार रैंकिंग के लिए वह मौजूद है:

डिफ़ॉल्ट	ब्रेकडाउन
processed	/tags, /categories, /templates, /broadcasts, /sending-domains, /recipient-domains
delivered	/sending-ips, /mailbox-providers, /mailbox-provider-regions
unique_opens	/locations, /clients
bounced	/bounce-codes
complained	/complaint-types

include_trend=true हर रो में प्रति-बकेट रेट सीरीज़ जोड़ता है, स्पार्कलाइन के लिए तैयार। यह tag, category, template, sending-domain, sending-IP, recipient-domain, mailbox-provider, और mailbox-provider-region ब्रेकडाउन पर लागू होता है।

सारांश और टाइम-सीरीज़ एंडपॉइंट प्रति रिक्वेस्ट एक आयाम फ़िल्टर भी स्वीकार करते हैं। 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 दिन है।

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

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

अगले कदम

ईमेल मेट्रिक्स: डैशबोर्ड इन आँकड़ों को कैसे प्रस्तुत करता है और कब कार्रवाई करनी चाहिए
Stats summary रेफ़रेंस: हर फ़ील्ड, फ़िल्टर, और दर फ़ॉर्मूला
Sending health रेफ़रेंस: निर्णय, उसके प्रति-दर सिग्नल, और उनकी सीमाएँ
Events और webhooks: जब एग्रीगेट पर्याप्त न हो तब प्रति-प्राप्तकर्ता स्ट्रीम