SDK
ओपन और क्लिक ट्रैकिंग
`emails.getTracking` और पूरा `tracking` संसाधन।
एक संदेश
const report = await openemail.emails.getTracking('msg_…') console.log(report.openCount, 'opens from', report.recipients.length, 'recipients')for (const link of report.links) console.log(link.url, link.clickCount)जो संदेश कभी ट्रैक ही नहीं हुआ, वह ख़ाली रिपोर्ट नहीं बल्कि ऐसा OpenEmailApiError फेंकता है जिसका isNotFound true है। "हमने कुछ दर्ज नहीं किया" और "इसे किसी ने नहीं खोला" अलग-अलग उत्तर हैं और उन्हें एक ही प्रतिक्रिया साझा नहीं करनी चाहिए।
पूरे मेलबॉक्स में
await openemail.tracking.list({ opened: false, days: 7, limit: 100 })await openemail.tracking.getStats({ days: 30, offsetMinutes: -new Date().getTimezoneOffset() })await openemail.tracking.get('msg_…')await openemail.tracking.listOpens('msg_…', { includeMachine: true })await openemail.tracking.listClicks('msg_…')list, listOpens और listClicks सादे arrays में resolve होते हैं। get, listOpens और listClicks या तो msg_… send id लेते हैं या tracking रिकॉर्ड की अपनी tmsg_…।
यह emails पर फ़ील्ड होने के बजाय अपने आप में एक संसाधन है, और इसका कारण है दायरा: emails send रिकॉर्ड सूचीबद्ध करता है, जो केवल उसी मेल के लिए मौजूद होते हैं जिसे इस API ने संभाला। composer, MCP tools और assistant — ये सब उसके बिना भेजते हैं, इसलिए emails पर बनी रिपोर्ट मेलबॉक्स के बारे में नहीं, आपके API ट्रैफ़िक के बारे में रिपोर्ट होती।
आंकड़ों को ईमानदारी से पढ़ना
| जोड़ी | इसका क्या अर्थ है |
|---|---|
| `opens` / `clicks` | जो लागू हुआ: संदेश pixel या दोबारा लिखे गए लिंक के साथ गया या नहीं। |
| `opened` / `clicked` | जो हुआ। |
| `openCount` | गिने गए हिट। स्कैनर और प्राइवेसी प्रॉक्सी शामिल नहीं। |
| `openCountRaw` | हर हिट। इसे एंगेजमेंट के तौर पर पेश करने से ही ओपन रेट 100% से ऊपर चला जाता है। |
| `attributable` | क्या किसी पढ़े जाने को किसी नामित प्राप्तकर्ता से जोड़ा भी जा सकता है। |
tracking.getStats से मिलने वाली दरें ट्रैक किए गए संदेशों पर होती हैं, भेजे गए सभी संदेशों पर कभी नहीं। वरना जो मेलबॉक्स दस में से एक संदेश ट्रैक करता है, वह ढह गया-सा दिखेगा।
पैरामीटर: tracking.list
openedboolean- `true` उन संदेशों को चुनता है जिनमें कम से कम एक गिना गया ओपन है, `false` उन ट्रैक किए गए संदेशों को चुनता है जिनमें एक भी नहीं। इनमें से कोई डिफ़ॉल्ट नहीं है, और `false` का मतलब कभी भी बिना ट्रैकिंग वाला मेल नहीं होता, जो इस सूची में आता ही नहीं।
clickedboolean- गिने गए क्लिक के लिए वही फ़िल्टर, `opened` से स्वतंत्र रूप से लागू। दोनों दिए जा सकते हैं, और संदेशों को दोनों शर्तें पूरी करनी होंगी।
daysnumber- अभी से कितने दिन पीछे तक देखना है, 1 से 365 तक और डिफ़ॉल्ट 30; इस दायरे से बाहर होने पर 422 मिलता है। यह विंडो इस आधार पर मापी जाती है कि ट्रैकिंग रिकॉर्ड कब बना, और केवल वही रिकॉर्ड सूचीबद्ध होते हैं जिनका भेजा जाना सचमुच हुआ।
limitnumber- अधिकतम इतने संदेश, 1 से 200 तक और डिफ़ॉल्ट 50, नए से पुराने क्रम में। कोई cursor नहीं है: यह किसी फ़ीड के बजाय एक विंडो पर बनी रिपोर्ट है, इसलिए इसकी सीमा `days` और `limit` तय करते हैं और इसे पूरा का पूरा पढ़ा जाता है।
रिस्पॉन्स: TrackingResource
object'tracking'- अपने आप में लाई गई रिपोर्ट पर हमेशा `'tracking'`, चाहे वह `tracking.get`, `tracking.list` या `emails.getTracking` से आई हो। वही रिपोर्ट जब किसी प्राप्त किए गए संदेश पर `email.tracking` के रूप में नेस्ट होती है, तो यह key उसमें नहीं होती, क्योंकि वहाँ वह उस object का हिस्सा है, न कि अलग से लाई गई कोई चीज़।
idstring- ट्रैकिंग रिकॉर्ड की अपनी id, `tmsg_…`। प्रति-हिट कॉल `listOpens` और `listClicks` इसी पर आधारित होती हैं; उन्हें दी गई कोई `msg_…` पहले इसी में बदली जाती है।
sendIdstring | null- वह `msg_…` send जिससे यह संबंधित है, और जहाँ कोई send रिकॉर्ड नहीं लिखा गया वहाँ null। कंपोज़र, MCP का `sendEmail` और असिस्टेंट — तीनों इसके बिना भेजते हैं। ट्रैकिंग पूरे मेलबॉक्स को कवर करती है, केवल API ट्रैफ़िक को नहीं।
threadIdstring | null- ट्रांसमिशन के बाद भरा जाता है ताकि पढ़ने वाला UI संदेश दोबारा ढूँढ सके, और जहाँ ड्राइवर ने कुछ नहीं बताया वहाँ null। यह अनिवार्य नहीं है: जिस रिकॉर्ड में यह null है वह भी गिना जाता है।
messageIdstring | null- RFC 5322 Message-ID, हमारी id नहीं। यह भी ट्रांसमिशन के बाद भरा जाता है, और जहाँ ट्रांसपोर्ट ने भरने के लिए कुछ नहीं लौटाया वहाँ null।
subjectstring | null- subject, जैसा वह भेजते समय था। बिना subject के दर्ज संदेश पर null।
fromstring- भेजने वाला पता, जो send से जोड़कर लाने के बजाय रिकॉर्ड पर ही कॉपी कर दिया जाता है। रिपोर्टें घटना के बहुत बाद पढ़ी जाती हैं, और तब से सुधारा या हटाया गया कोई पता अन्यथा इतिहास को दोबारा लिख देता।
sourceEmailSource | (string & {})- इसे किस सतह ने भेजा: `composer`, `api`, `mcp`, `ai` या `queue`। टाइप खुला रखा गया है ताकि कोई ऐसी सतह, जिसका नाम यह SDK अभी नहीं लेता, breaking change न बने।
sentAtstring | null- संदेश कब गया, ISO-8601 क्षण के रूप में। जिस रिकॉर्ड का send कभी पूरा नहीं हुआ उस पर null। `tracking.list` उन्हें छोड़ देता है, `get` नहीं छोड़ता।
opensboolean- क्या इस संदेश पर pixel लगाया गया था। यह बताता है कि क्या किया गया, न कि अभी अकाउंट सेटिंग क्या कहती है।
clicksboolean- क्या इस संदेश के लिंक दोबारा लिखे गए थे। जब बॉडी में कोई लिंक ही नहीं था तो false, क्योंकि तब कुछ बदला ही नहीं गया और इसके उलट दावा करने वाले रिकॉर्ड को असली बाइट्स से मिलाया नहीं जा सकता।
openedboolean- क्या सभी कॉपियों में कहीं भी कोई गिना गया ओपन दर्ज हुआ। इसे `opens` के साथ मिलाकर पढ़ें: डेटा इसलिए न होना कि कुछ इकट्ठा ही नहीं हुआ, इस बात से अलग तथ्य है कि संदेश किसी ने पढ़ा ही नहीं।
clickedboolean- क्या कोई गिना गया क्लिक दर्ज हुआ। ओपन से ज़्यादा मज़बूत सबूत, क्योंकि लिंक पर न जाने की तुलना में इमेज कहीं ज़्यादा बार ब्लॉक होती हैं।
attributableboolean- क्या यहाँ का हर पढ़ा जाना किसी नामित प्राप्तकर्ता से जोड़ा जा सकता है। जैसे ही किसी बिना-श्रेय वाली कॉपी पर गिनी गई गतिविधि दिखती है, यह false हो जाता है — यही वह बहु-प्राप्तकर्ता स्थिति है जहाँ एक ही बॉडी एक ही token के तहत पूरी सूची को जाती है, इसलिए "Bob ने इसे नहीं खोला" लिखने से पहले इसे जाँच लें।
openCountnumber- वे ओपन जिन्हें किसी व्यक्ति द्वारा किया गया माना जाता है, सभी कॉपियों को जोड़कर। मशीनी हिट छोड़ दिए जाते हैं और तीस सेकंड के भीतर के दोहराव एक में मिला दिए जाते हैं, इसलिए पाठक के सामने यही आँकड़ा रखना चाहिए।
clickCountnumber- गिने गए क्लिक, सभी कॉपियों को जोड़कर। डुप्लिकेट हटाना प्रति संदेश नहीं बल्कि प्रति लिंक होता है, इसलिए कुछ सेकंड के अंतर पर खोले गए दो अलग लिंक दो क्लिक हैं।
openCountRawnumber- हर पिक्सेल फ़ेच, स्कैनर और प्राइवेसी प्रॉक्सी समेत। `openCountRaw - openCount` बताता है कि क्लासिफ़ायर ने कितने अलग रखे, और यही अकेला सबूत है कि फ़िल्टरिंग हुई भी।
clickCountRawnumber- दोबारा लिखे गए लिंक पर हर विज़िट, मशीनी हिट और दोहराव समेत।
firstOpenAtstring | null- सभी प्रतियों में सबसे पहला गिना गया ओपन, और जब तक कोई नहीं है तब तक null। मशीन हिट इसे कभी आगे नहीं बढ़ातीं।
lastOpenAtstring | null- सभी प्रतियों में सबसे हालिया गिना गया ओपन; जब तक कोई नहीं है, null।
firstClickAtstring | null- सभी प्रतियों में सबसे पहला गिना गया क्लिक; जब तक कोई नहीं है, null।
lastClickAtstring | null- सभी प्रतियों में सबसे हालिया गिना गया क्लिक; जब तक कोई नहीं है, null।
recipientsTrackingRecipientResource[]- प्रत्येक ट्रैक की गई प्रति के लिए एक प्रविष्टि: जहाँ ट्रांसपोर्ट बाइट्स को हर व्यक्ति के लिए अलग होने देता है वहाँ प्रति प्राप्तकर्ता एक, और जहाँ नहीं देता वहाँ एक साझा प्रविष्टि। साझा प्रविष्टि तब तक हटा दी जाती है जब तक उस पर वास्तव में कुछ दर्ज न हुआ हो, इसलिए बिना किसी हिट वाली "कोई" पंक्ति असली नामों के बगल में कभी नहीं बैठती।
recipients[].emailstring | null- यह प्रति किसे गई, lowercase में और जैसी वह भेजते समय थी। ठीक तभी null जब `attributed` false हो।
recipients[].kind'to' | 'cc' | 'bcc' | null- पता किस header पर आया था, ताकि रिपोर्ट वैसी ही पढ़ी जाए जैसा संदेश था। साझा प्रति पर null, जो किसी एक पते की नहीं होती।
recipients[].attributedboolean- क्या यह पंक्ति किसी व्यक्ति का नाम बताती है। इसे `email` से पहले पढ़ें: false का अर्थ है साझा प्रति, जो किसी भी हिट के उस पर आते ही सूचीबद्ध हो जाती है, और उस हिट पर नाम चिपकाना — एकमात्र प्राप्तकर्ता वाले संदेश पर भी — ठीक वही तथ्य गढ़ना होगा जो यह तंत्र दे ही नहीं सकता।
recipients[].openCountnumber- केवल इसी प्रति पर गिने गए ओपन, संदेश के कुल योग जैसी ही छूटों के साथ: मशीन हिट हटा दी जाती हैं, और तीस सेकंड के भीतर की पुनरावृत्तियाँ एक में समेट दी जाती हैं।
recipients[].clickCountnumber- केवल इसी प्रति पर गिने गए क्लिक, जिनका दोहराव प्रति प्रति नहीं बल्कि प्रति लिंक हटाया जाता है।
recipients[].firstOpenAtstring | null- इस प्रति पर सबसे पहला गिना गया ओपन; जब तक कोई नहीं है, null।
recipients[].lastOpenAtstring | null- इस प्रति पर सबसे हालिया गिना गया ओपन; जब तक कोई नहीं है, null।
recipients[].firstClickAtstring | null- इस प्रति पर सबसे पहला गिना गया क्लिक; जब तक कोई नहीं है, null।
recipients[].lastClickAtstring | null- इस प्रति पर सबसे हालिया गिना गया क्लिक; जब तक कोई नहीं है, null।
linksTrackingLinkResource[]- इस संदेश में फिर से लिखा गया हर लिंक, उसी क्रम में जिसमें वह body में बैठा था। जहाँ कोई नहीं था वहाँ खाली: `clicks` बंद रखकर भेजा गया संदेश, या वह जिसकी body में कोई लिंक था ही नहीं।
links[].idstring- लिंक की अपनी id, `lnk_…`। यही वह मान है जिसका नाम किसी click पंक्ति का `linkId` लेता है, इसलिए `listClicks` से आई हिट को यहाँ की प्रविष्टि से मिलाया जा सकता है।
links[].urlstring- लिंक वास्तव में कहाँ जाता है, जैसा वह फिर से लिखे जाने से पहले संदेश में था। रीडायरेक्टर किसी id को वापस इसी में हल करता है और आगंतुक को आगे भेज देता है।
links[].labelstring | null- ऐंकर टेक्स्ट, जैसा वह संदेश में दिखा, या null जहाँ लिंक के पास कोई नहीं था, जैसे कोई छवि या नंगा URL। यह इसलिए है ताकि रिपोर्ट तीन ट्रैकिंग पैरामीटर वाला URL उद्धृत करने के बजाय "प्राइसिंग लिंक" कह सके, और यह कभी `url` की जगह नहीं लेता।
links[].clickCountnumber- इस लिंक पर गिनी गई विज़िट, सभी प्रतियों पर जोड़कर। संदेश के `clickCount` जैसी ही प्रति-लिंक तीस-सेकंड की विंडो।
links[].clickCountRawnumber- इस लिंक पर हर विज़िट, मशीन हिट और पुनरावृत्तियाँ सहित।