PHP
Open और click tracking
`emails->getTracking` और पूरा `tracking` namespace।
एक संदेश
$report = $client->emails->getTracking('msg_3f9a1c07d2b84e6a9c5b1f20'); echo $report['openCount'], ' opens from ', count($report['recipients']), ' recipients', PHP_EOL; foreach ($report['links'] as $link) { echo $link['url'], ' ', $link['clickCount'], PHP_EOL;}जो संदेश कभी track नहीं हुआ, वह ख़ाली रिपोर्ट नहीं, बल्कि NotFoundException throw करता है, जिसका isNotFound() true होता है। “हमने कुछ दर्ज नहीं किया” और “किसी ने नहीं खोला” अलग-अलग जवाब हैं और इन्हें एक ही जवाब साझा नहीं करना चाहिए। test कुंजी से भेजा गया संदेश कभी track नहीं होता, इसलिए वह हमेशा इसे throw करता है।
पूरे मेलबॉक्स में
$unopened = $client->tracking->list(opened: false, days: 7, limit: 100);$stats = $client->tracking->getStats(days: 30, offsetMinutes: intdiv((int) date('Z'), 60));$report = $client->tracking->get('msg_3f9a1c07d2b84e6a9c5b1f20');$opens = $client->tracking->listOpens('msg_3f9a1c07d2b84e6a9c5b1f20', includeMachine: true);$clicks = $client->tracking->listClicks('msg_3f9a1c07d2b84e6a9c5b1f20'); echo count($unopened), ' unopened, ', $stats['openRate'], '% opened', PHP_EOL;echo count($opens), ' opens and ', count($clicks), ' clicks on ', $report['id'], PHP_EOL;list, listOpens और listClicks एक OpenEmail\Result\Page लौटाते हैं, और listAll, iterate, listAllOpens, iterateOpens, listAllClicks और iterateClicks आपके लिए हर पेज पर चलते हैं। get, listOpens और listClicks या तो msg_… send id लेते हैं या ट्रैकिंग रिकॉर्ड की अपनी tmsg_…।
emails पर मेथड के बजाय एक अलग namespace, और इसका कारण कवरेज है: emails send रिकॉर्ड सूचीबद्ध करता है, जो सिर्फ़ उसी मेल के लिए होते हैं जिसे इस API ने संभाला। composer, MCP टूल और assistant सभी इसके बिना भेजते हैं, इसलिए emails पर बनी रिपोर्ट मेलबॉक्स के बारे में नहीं, आपके API ट्रैफ़िक के बारे में होती।
आंकड़ों को ईमानदारी से पढ़ना
| जोड़ी | इसका क्या अर्थ है |
|---|---|
| opens और clicks | जो लागू हुआ: संदेश pixel या दोबारा लिखे गए लिंक के साथ गया या नहीं। |
| opened और clicked | जो हुआ। |
| openCount | गिने गए हिट। स्कैनर और प्राइवेसी प्रॉक्सी शामिल नहीं। |
| openCountRaw | हर हिट। इसे एंगेजमेंट के तौर पर पेश करने से ही ओपन रेट 100% से ऊपर चला जाता है। |
| attributable | क्या किसी पढ़े जाने को किसी नामित प्राप्तकर्ता से जोड़ा भी जा सकता है। |
tracking->getStats की दरें “ट्रैक किए गए” संदेशों पर होती हैं, भेजी गई हर चीज़ पर कभी नहीं। वरना जो मेलबॉक्स दस में से एक संदेश ट्रैक करता है वह ऐसा दिखता मानो ढह गया हो। openRate और clickRate एक दशमलव स्थान तक पूर्णांकित प्रतिशत हैं, जैसे 42.5, 0 और 1 के बीच के भिन्न नहीं।
पैरामीटर: tracking->list
openedbool- `true` उन संदेशों को चुनता है जिनमें कम से कम एक गिना गया ओपन है, `false` उन ट्रैक किए गए संदेशों को चुनता है जिनमें एक भी नहीं। इनमें से कोई डिफ़ॉल्ट नहीं है, और `false` का मतलब कभी भी बिना ट्रैकिंग वाला मेल नहीं होता, जो इस सूची में आता ही नहीं।
clickedbool- गिने गए क्लिक के लिए वही फ़िल्टर, `opened` से स्वतंत्र रूप से लागू। दोनों दिए जा सकते हैं, और संदेशों को दोनों शर्तें पूरी करनी होंगी।
daysint- अभी से कितने दिन पीछे देखना है, 1 से 365, डिफ़ॉल्ट 30, और उस सीमा से बाहर 422 है। विंडो ट्रैकिंग रिकॉर्ड बनने के समय से मापी जाती है, और सिर्फ़ वे रिकॉर्ड सूचीबद्ध होते हैं जिनका send सच में बाहर गया।
minutesint- इसकी जगह मिनटों में विंडो, 1 से 527040, जो दोनों सेट होने पर `days` पर भारी पड़ती है। एक दिन से छोटी विंडो को बारीक `grain` चाहिए।
grainstring- `minute`, `hour` या `day`, डिफ़ॉल्ट `day`। यह सिर्फ़ विंडो की शुरुआत को नीचे की ओर पूर्णांकित करता है, ताकि यह सूची उसी grain पर पढ़े गए `getStats` से मेल खाए, और जवाब में किसी चीज़ का आकार नहीं बदलता।
limitint- हर पेज पर रिपोर्ट, 1 से 200, डिफ़ॉल्ट 50, सबसे नई पहले। अगले पेज के लिए पेज का `nextCursor` उन्हीं फ़िल्टरों के साथ `cursor:` के रूप में वापस भेजें, या `listAll` और `iterate` को पूरी विंडो पर चलने दें।
cursorstring- पिछले पेज का `nextCursor`, एक `tmsg_` id।
apiKeystring- क्लाइंट की कुंजी के बजाय इस कुंजी से सूची लेता है।
जवाब: ट्रैकिंग रिपोर्ट
emails->getTracking और tracking->get एक रिपोर्ट को camelCase कुंजियों वाले array के रूप में लौटाते हैं, और tracking->list उनका एक पेज लौटाता है।
objectstring- अपने आप में लाई गई रिपोर्ट पर हमेशा `tracking`, चाहे `tracking->get`, `tracking->list` या `emails->getTracking` से। वही रिपोर्ट जब `emails->get` से आए संदेश पर `tracking` के रूप में भीतर आती है तो यह कुंजी नहीं होती, क्योंकि वहाँ वह उस संदेश का हिस्सा है, अलग से लाई गई चीज़ नहीं।
idstring- ट्रैकिंग रिकॉर्ड की अपनी id, `tmsg_…`। `listOpens` और `listClicks` इसी पर आधारित हैं, और उन्हें दी गई `msg_…` को पहले इसी के रूप में खोजा जाता है।
sendIdstring or null- वह `msg_…` send जिससे यह जुड़ा है, और जहाँ कोई send रिकॉर्ड नहीं लिखा गया वहाँ null। composer, MCP का `sendEmail` और assistant सभी बिना send रिकॉर्ड के भेजते हैं। tracking सिर्फ़ API ट्रैफ़िक नहीं, बल्कि पूरे मेलबॉक्स को कवर करता है।
threadIdstring or null- ट्रांसमिशन के बाद भरा जाता है ताकि पढ़ने वाला UI संदेश दोबारा ढूँढ सके, और जहाँ ड्राइवर ने कुछ नहीं बताया वहाँ null। यह अनिवार्य नहीं है: जिस रिकॉर्ड में यह null है वह भी गिना जाता है।
messageIdstring or null- RFC 5322 Message-ID, हमारी id नहीं। यह भी ट्रांसमिशन के बाद भरा जाता है, और जहाँ ट्रांसपोर्ट ने भरने के लिए कुछ नहीं लौटाया वहाँ null।
subjectstring or null- भेजने के समय जैसा subject था। जो संदेश बिना subject के दर्ज हुआ उस पर null।
fromstring- भेजने वाला पता, जो send से जोड़कर लाने के बजाय रिकॉर्ड पर ही कॉपी कर दिया जाता है। रिपोर्टें घटना के बहुत बाद पढ़ी जाती हैं, और तब से सुधारा या हटाया गया कोई पता अन्यथा इतिहास को दोबारा लिख देता।
sourcestring- किस सतह ने इसे भेजा: `composer`, `api`, `mcp`, `ai` या `queue`। ऐसी सतह भी दिख सकती है जिसका नाम यह पैकेज अभी नहीं लेता, इसलिए अज्ञात मान को error के बजाय जानकारी मानें।
sentAtstring or null- संदेश कब गया, ISO 8601 क्षण के रूप में। जिस रिकॉर्ड का send कभी पूरा नहीं हुआ उस पर null। `tracking->list` उन्हें छोड़ देता है, `get` नहीं।
opensbool- क्या इस संदेश पर pixel लगाया गया था। यह बताता है कि क्या किया गया, न कि अभी अकाउंट सेटिंग क्या कहती है।
clicksbool- क्या इस संदेश के लिंक दोबारा लिखे गए। जब बॉडी में कोई लिंक न हो तो false, क्योंकि तब कुछ बदला ही नहीं और इसके उलट दावा करने वाला रिकॉर्ड बाइट्स से मेल नहीं खा सकता।
openedbool- क्या सभी कॉपियों में कहीं भी कोई गिना गया ओपन दर्ज हुआ। इसे `opens` के साथ मिलाकर पढ़ें: डेटा इसलिए न होना कि कुछ इकट्ठा ही नहीं हुआ, इस बात से अलग तथ्य है कि संदेश किसी ने पढ़ा ही नहीं।
clickedbool- क्या कोई गिना गया क्लिक दर्ज हुआ। ओपन से ज़्यादा मज़बूत सबूत, क्योंकि लिंक पर न जाने की तुलना में इमेज कहीं ज़्यादा बार ब्लॉक होती हैं।
attributablebool- क्या यहाँ का हर पढ़ा जाना किसी नामित प्राप्तकर्ता से जोड़ा जा सकता है। जैसे ही किसी बिना-श्रेय वाली कॉपी पर गिनी गई गतिविधि दिखती है, यह False हो जाता है। यही वह बहु-प्राप्तकर्ता स्थिति है जहाँ एक ही बॉडी एक ही token के तहत पूरी सूची को जाती है, इसलिए "Bob ने इसे नहीं खोला" लिखने से पहले इसे जाँच लें।
openCountint- वे ओपन जिन्हें किसी व्यक्ति द्वारा किया गया माना जाता है, सभी कॉपियों को जोड़कर। मशीनी हिट छोड़ दिए जाते हैं और तीस सेकंड के भीतर के दोहराव एक में मिला दिए जाते हैं, इसलिए पाठक के सामने यही आँकड़ा रखना चाहिए।
clickCountint- गिने गए क्लिक, सभी कॉपियों को जोड़कर। डुप्लिकेट हटाना प्रति संदेश नहीं बल्कि प्रति लिंक होता है, इसलिए कुछ सेकंड के अंतर पर खोले गए दो अलग लिंक दो क्लिक हैं।
openCountRawint- हर pixel fetch, स्कैनर और प्राइवेसी प्रॉक्सी समेत। `openCountRaw` में से `openCount` घटाने पर पता चलता है कि कितने अलग रखे गए, मशीनी fetch और तीस सेकंड के भीतर के दोहराव मिलाकर, और यही इकलौता उपलब्ध सबूत है कि छँटाई हुई भी।
clickCountRawint- दोबारा लिखे गए लिंक पर हर विज़िट, मशीनी हिट और दोहराव समेत।
firstOpenAtstring or null- सभी प्रतियों में सबसे पहला गिना गया open, और कोई न होने पर null। मशीनी hits इसे कभी नहीं हिलातीं।
lastOpenAtstring or null- सभी प्रतियों में सबसे हालिया गिना गया ओपन; जब तक कोई नहीं है, null।
firstClickAtstring or null- सभी प्रतियों में सबसे पहला गिना गया क्लिक; जब तक कोई नहीं है, null।
lastClickAtstring or null- सभी प्रतियों में सबसे हालिया गिना गया क्लिक; जब तक कोई नहीं है, null।
recipientsarray- प्रत्येक ट्रैक की गई प्रति के लिए एक प्रविष्टि: जहाँ ट्रांसपोर्ट बाइट्स को हर व्यक्ति के लिए अलग होने देता है वहाँ प्रति प्राप्तकर्ता एक, और जहाँ नहीं देता वहाँ एक साझा प्रविष्टि। साझा प्रविष्टि तब तक हटा दी जाती है जब तक उस पर वास्तव में कुछ दर्ज न हुआ हो, इसलिए बिना किसी हिट वाली "कोई" पंक्ति असली नामों के बगल में कभी नहीं बैठती।
linksarray- इस संदेश में फिर से लिखा गया हर लिंक, उसी क्रम में जिसमें वह body में बैठा था। जहाँ कोई नहीं था वहाँ खाली: `clicks` बंद रखकर भेजा गया संदेश, या वह जिसकी body में कोई लिंक था ही नहीं।
recipients में हर प्रविष्टि
emailstring or null- यह कॉपी किसे गई, lowercase में और भेजने के समय जैसा था। null ठीक तभी होता है जब `attributed` false हो।
kindstring or null- `to`, `cc` या `bcc`: पता किस हेडर में था, ताकि रिपोर्ट वैसे ही पढ़ी जाए जैसे संदेश पढ़ा गया था। साझा कॉपी पर null, जो किसी एक पते की नहीं है।
attributedbool- क्या यह पंक्ति किसी व्यक्ति का नाम बताती है। इसे `email` से पहले पढ़ें: false का अर्थ है साझा प्रति, जो किसी भी हिट के उस पर आते ही सूचीबद्ध हो जाती है, और उस हिट पर नाम चिपकाना, एकमात्र प्राप्तकर्ता वाले संदेश पर भी, ठीक वही तथ्य गढ़ना होगा जो यह तंत्र दे ही नहीं सकता।
openCountint- केवल इसी प्रति पर गिने गए ओपन, संदेश के कुल योग जैसी ही छूटों के साथ: मशीन हिट हटा दी जाती हैं, और तीस सेकंड के भीतर की पुनरावृत्तियाँ एक में समेट दी जाती हैं।
clickCountint- केवल इसी प्रति पर गिने गए क्लिक, जिनका दोहराव प्रति प्रति नहीं बल्कि प्रति लिंक हटाया जाता है।
firstOpenAtstring or null- इस प्रति पर सबसे पहला गिना गया ओपन; जब तक कोई नहीं है, null।
lastOpenAtstring or null- इस प्रति पर सबसे हालिया गिना गया ओपन; जब तक कोई नहीं है, null।
firstClickAtstring or null- इस प्रति पर सबसे पहला गिना गया क्लिक; जब तक कोई नहीं है, null।
lastClickAtstring or null- इस प्रति पर सबसे हालिया गिना गया क्लिक; जब तक कोई नहीं है, null।
links में हर प्रविष्टि
idstring- लिंक की अपनी id, `lnk_…`। यही वह मान है जिसका नाम click पंक्ति का `linkId` लेता है, ताकि `listClicks` से आए hit को यहाँ की प्रविष्टि से मिलाया जा सके।
urlstring- लिंक असल में कहाँ जाता है, जैसा दोबारा लिखे जाने से पहले संदेश में था। redirector id से इसे खोजता है और विज़िटर को आगे भेज देता है।
labelstring or null- संदेश में जैसा दिखा वैसा anchor text, या जहाँ link में कोई text न हो वहाँ null, जैसे कोई image या सादा URL। यह इसलिए है ताकि रिपोर्ट तीन tracking पैरामीटर वाले URL को उद्धृत करने के बजाय “pricing वाला link” कह सके, और यह कभी `url` की जगह नहीं लेता।
clickCountint- इस लिंक पर गिनी गई विज़िट, सभी प्रतियों पर जोड़कर। संदेश के `clickCount` जैसी ही प्रति-लिंक तीस-सेकंड की विंडो।
clickCountRawint- इस लिंक पर हर विज़िट, मशीन हिट और पुनरावृत्तियाँ सहित।