PHP

सूची और get

`emails->list`, `emails->listAll`, `emails->iterate`, `emails->get` और `emails->listEvents`।

emails->list

list_emails.php

$filters = ['status' => ['queued', 'scheduled'], 'from' => '[email protected]']; $first = $client->emails->list(...$filters, limit: 50);$second = $first->hasMore ? $client->emails->list(...$filters, limit: 50, cursor: $first->nextCursor) : null; echo count($first), ' ', $second === null ? 0 : count($second), PHP_EOL;

पेज एक OpenEmail\Result\Page है जिसमें items, hasMore और nextCursor होते हैं। उसके बाद वाले पेज के लिए nextCursor को उन्हीं फ़िल्टरों के साथ cursor: के रूप में वापस भेजें। फ़िल्टरों के एक array को हर कॉल में फैलाने से, जैसा ...$filters करता है, वे एक जैसे रहते हैं।

emails->iterate और emails->listAll

iterate_emails.php

foreach ($client->emails->iterate(status: 'failed') as $email) {    error_log($email['id'] . ' ' . ($email['lastError'] ?? ''));} $failures = $client->emails->listAll(status: 'failed', from: '[email protected]');echo count($failures), PHP_EOL;

दोनों आपके लिए nextCursor का पीछा करते हैं। iterate एक Generator लौटाता है जो पेज तभी लाता है जब चलना वहाँ पहुँचता है, इसलिए foreach से break करने पर रिक्वेस्ट रुक जाती हैं, जबकि listAll एक array लौटाने से पहले हर पेज पर चलता है, इसलिए उसे ऐसा फ़िल्टर दें जो ख़त्म हो। दोनों में keyset paging है, इसलिए बीच में आने वाला संदेश इसे कोई पंक्ति छोड़ने पर मजबूर नहीं कर सकता, जैसा offset के साथ होता।

emails->get और emails->listEvents

get_email.php

$email = $client->emails->get('msg_3f9a1c07d2b84e6a9c5b1f20');echo $email['status'], PHP_EOL;print_r($email['recipients']); $events = $client->emails->listAllEvents('msg_3f9a1c07d2b84e6a9c5b1f20'); foreach ($events as $event) {    echo $event['type'], ' ', $event['createdAt'], PHP_EOL;}

get अकेली कॉल है जो recipients लौटाती है, हर पते के लिए एक array जिसमें उसका अपना status, error और deliveredAt होता है। पचास संदेशों की सूची, जिसमें हर संदेश अपने प्राप्तकर्ता लिए हो, रिपोर्ट का ऐसा पेज है जो किसी ने माँगा नहीं।

listEvents एक send की event श्रृंखला पढ़ता है, सबसे पुरानी पहले: email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened और बाकी, हर एक के साथ एक data array जिसका आकार उसके type पर निर्भर करता है। listAllEvents और iterateEvents आपके लिए पूरी श्रृंखला पर चलते हैं। वेबहुक इन्हीं events का एक हिस्सा होते ही पहुँचाते हैं, इसलिए जब कोई वेबहुक छूट जाए तो यहीं देखें।

पैरामीटर

statusstring or array: एक या कई status (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), जो दिए गए किसी भी एक से मेल खाते हैं। `bounced` का मतलब है कि संदेश जिन प्राप्तकर्ताओं को गया वे सभी bounce हुए, जबकि जो संदेश कुछ के लिए bounce हुआ और बाकी तक पहुँचा, वह `partial` होता है। क्लाइंट array को कॉमा से अलग किए गए एक मान के रूप में भेजता है क्योंकि सर्वर कॉमा पर बाँटता है, और समूह के बाहर का मान अज्ञात मान का नाम लेने वाला 422 होता है।
broadcastIdstring: सिर्फ़ एक ब्रॉडकास्ट की कॉपियाँ, `broadcasts->send` से मिली `brd_` id। ब्रॉडकास्ट जिस भी व्यक्ति तक पहुँचता है उसे अपना अलग संदेश मिलता है, इसलिए यह बताता है कि यह किन्हें गया और हर कॉपी के साथ क्या हुआ। `broadcasts->listRecipients` इन्हीं लोगों को उनके opens, clicks और unsubscribes के साथ सूचीबद्ध करता है।
fromstring: भेजने वाले पते पर सटीक मिलान, जैसा वह दर्ज हुआ था, यानी छोटे अक्षरों में सादा `addr@host`। पंक्ति हर display name हटाकर लिखी जाती है, इसलिए `Acme <[email protected]>` जैसा angle-addr किसी से मेल नहीं खाता। तुलना से पहले आपका मान छोटे अक्षरों में बदला जाता है, और यह बराबरी है, prefix या डोमेन मिलान नहीं।
scheduledFromDateTimeInterface or string: सिर्फ़ इस क्षण या उसके बाद के लिए शेड्यूल किए गए संदेश। `scheduledTo:` और `status: ['scheduled', 'queued']` के साथ यह किसी अवधि में बाहर जाने का इंतज़ार कर रहे संदेशों की सूची देता है, जैसा ऐप का कैलेंडर करता है। जिस संदेश में `scheduledAt` नहीं है उसे छोड़ दिया जाता है। UTC में क्षण के रूप में भेजा जाने वाला `DateTimeInterface`, या offset वाला ISO 8601 क्षण पास करें: बिना समय वाली तारीख़ की स्ट्रिंग इन दोनों फ़िल्टरों द्वारा अस्वीकार की जाती है।
scheduledToDateTimeInterface or string: सिर्फ़ वे संदेश जो इस क्षण या पहले के लिए शेड्यूल हैं। `scheduledTo:` के बाद का `scheduledFrom:` 422 `invalid_parameter` है।
limitint: इस पेज की पंक्तियाँ, 1 से 100, डिफ़ॉल्ट 25। उस सीमा से बाहर का मान सीमा में काटे जाने के बजाय 422 के रूप में अस्वीकार होता है। `listAll` और `iterate` पर यह उनके लाए हर पेज का आकार है।
cursorstring: जिस संदेश id (`msg_…`) से पेजिंग करनी है। offset नहीं, keyset: पंक्तियाँ उस संदेश के `createdAt` से सख़्ती से पुरानी लौटती हैं, इसलिए पेज के बीच आए sends कोई पंक्ति आपसे आगे नहीं धकेल सकते। जो id इस वर्कस्पेस के किसी संदेश का नाम नहीं लेती वह 400 `invalid_cursor` है।
apiKeystring: क्लाइंट की कुंजी के बजाय इस कुंजी से सूची लेता है।

कुछ पतों तक सीमित कुंजी सिर्फ़ उन पतों से भेजे गए संदेश पढ़ती है जिन्हें वह कवर करती है, और पेज उस फ़िल्टर के बाद काटा जाता है, इसलिए आख़िरी को छोड़ हर पेज में फिर भी limit पंक्तियाँ होती हैं। जो from: कुंजी कवर नहीं करती वह 403 के बजाय एक ख़ाली आख़िरी पेज लौटाता है।

जवाब: OpenEmail\Result\Page

itemsarray: संदेशों का एक पेज, `createdAt` के अनुसार सबसे नए पहले, API के `data` लिफ़ाफ़े से निकाला हुआ। list की पंक्तियाँ प्रति-पता `recipients` विवरण कभी नहीं ढोतीं। वह `get` पर है।
hasMorebool: क्या इस पेज के आगे भी और पंक्तियाँ फ़िल्टर से मेल खाती हैं। इसका उत्तर दूसरी count query से नहीं, बल्कि `limit` से एक पंक्ति ज़्यादा लाकर दिया जाता है।
nextCursorstring or null: `cursor:` के रूप में वापस भेजी जाने वाली id, और आख़िरी पेज पर null। `iterate` और `listAll` तब रुकते हैं जब यह null हो या `hasMore` false हो, क्योंकि जो पेज और होने का दावा करे पर कोई cursor न बताए, वह हमेशा लूप करता रहेगा।

हर आइटम

objectstring: इस सूची की पंक्ति पर हमेशा `email`।
idstring: इस API की अपनी id, `msg_…`। बाक़ी हर emails कॉल यही लेती है, और cursor भी इसी का नाम लेता है।
statusstring: संदेश अपने जीवन में कहाँ है। `partial` failed का कोई रूप नहीं बल्कि अपने आप में एक स्थिति है: कुछ प्राप्तकर्ताओं के पास वह पहुँच चुका है और उसे वापस नहीं लिया जा सकता, इसलिए दोबारा कोशिश करना ग़लत है। `bounced` का अर्थ है कि भेजे जाने के बाद वह हर प्राप्तकर्ता से बाउंस हो गया, इसलिए वह किसी के पास नहीं है, और `get` में हर प्राप्तकर्ता इसका कारण बताता है।
modestring: `live` या `test`, उसी कुंजी से लिया गया जिसने भेजा। test send यहाँ दर्ज होता है और कभी प्रेषित नहीं होता।
fromstring: वह पता जिसके तहत send की अनुमति मिली, सादा और lowercase करके सहेजा गया, इसलिए `from` पर दिया गया display name नेटवर्क पर तो जाता है पर यहाँ नहीं रखा जाता। यह array के बजाय सादी स्ट्रिंग है क्योंकि यही वह पहचान है जिसे अनुमति मिली: कुंजी के send scope के बाहर का पता, जो न उसके किसी डोमेन पर है और न उस पर नामित है, 403 के साथ अस्वीकार किया जाता है, उसे कभी चुपचाप scope के भीतर के किसी पते से नहीं बदला जाता।
subjectstring or null: सहेजा गया subject। जो संदेश बिना subject के दर्ज हुआ उस पर null।
messageIdstring or null: RFC 5322 Message-ID, हमारी id नहीं। MIME बनने तक null, और बाहर जाते समय भेजने वाली सेवा इसे फिर से लिखती है, इसलिए बाद में आने वाला bounce या DSN एक अलग id रखता है और इसके बजाय `id` से जुड़ता है।
threadIdstring or null: वह thread जिसका यह संदेश है, जहाँ कोई दिया या सौंपा गया हो। अन्यथा null।
transportstring or null: बाइट्स कैसे गए। dispatch होने तक null। सहेजे गए रिकॉर्ड में ऐसे transport के नाम भी हो सकते हैं जो अब इस्तेमाल नहीं होते, इसलिए जो मान आप न जानते हों उसे error के बजाय जानकारी मानें।
attemptsint: संदेश के कितने dispatch प्रयास हो चुके हैं; पहले प्रयास से पहले 0।
lastErrorstring or null: सबसे हाल की dispatch error, किसी व्यक्ति के लिए लिखी गई। जब तक कुछ विफल न हुआ हो तब तक null।
scheduledAtstring or null: संदेश कब जाना है, ISO 8601 क्षण के रूप में। null सिर्फ़ उस तुरंत send पर जिसमें रद्द करने की कोई अवधि न हो: अवधि बस एक छोटी देरी है और कुछ नहीं, इसलिए `cancellableForSeconds` भी इसे भरता है, ऐसी पंक्ति पर जिसका `status` `scheduled` के बजाय `queued` है।
cancellableUntilstring or null: वह क्षण जब संदेश रवाना होना है; किसी भी टाले गए send पर यह `scheduledAt` जैसा ही मान रखता है और न टाले गए पर null। यह दिखाने के लिए एक timestamp है, वह परीक्षा नहीं जो सर्वर करता है: `cancel` `status` पर शाखा बनाता है, और संदेश को केवल तब तक रोकता है जब तक वह `queued` या `scheduled` हो।
sentAtstring or null: कब गया। dispatch पूरा होने तक null, इसीलिए branch करने के लिए यह नहीं, बल्कि `status` फ़ील्ड है।
tagsarray: send पर दिए गए लेबल, जो वैसे ही लौटाए जाते हैं और कभी interpret नहीं किए जाते। हमेशा एक array, कोई सेट न होने पर ख़ाली और कभी null नहीं, और सिर्फ़ लौटाए जाते हैं: यह सूची `status`, `from`, `broadcastId` और शेड्यूल की अवधि पर फ़िल्टर करती है, इसलिए tag संदेश ढूँढने का तरीक़ा नहीं, बल्कि संदेश से पढ़ी जाने वाली चीज़ है।
broadcastIdstring or null: वह `brd_` broadcast जिसकी यह संदेश एक कॉपी है, या अकेले भेजे गए संदेश के लिए null।
sourcestring: किस सतह ने send माँगा: `composer`, `api`, `mcp`, `ai` या `queue`। `api` यही क्लाइंट है।
createdAtstring: send का रिकॉर्ड कब लिखा गया, जो dispatch से पहले होता है। यही वह फ़ील्ड है जिससे सूची क्रम में लगती है और जिससे cursor तुलना करता है।
trackingarray: engagement का सारांश, सिर्फ़ उस पंक्ति पर मौजूद जिसका संदेश track किया गया, वरना अनुपस्थित। अनुपस्थित होना ही “क्या इसे track किया गया” का जवाब है, जबकि 0 वाला `openCount` “किसी ने नहीं खोला” पढ़ा जाता, इसलिए कुंजी मानकर चलने के बजाय इसे `?? null` के साथ पढ़ें।
translationarray: list की पंक्ति पर कभी मौजूद नहीं: अनुवाद का रिकॉर्ड संग्रहित रिक्वेस्ट में रहता है, जिसे list जानबूझकर नहीं लाती। यहाँ इसकी अनुपस्थिति इस बारे में कुछ नहीं कहती कि संदेश अनूदित हुआ था या नहीं। `get` से पूछें।

किसी आइटम की ट्रैकिंग

opensbool: क्या यह संदेश pixel के साथ गया। यह वही है जो इस संदेश पर लागू हुआ, न कि वह जो खाता-सेटिंग अब कहती है।
clicksbool: क्या इस संदेश के लिंक दोबारा लिखे गए। जब बॉडी में दोबारा लिखने को कोई लिंक न हो तो false, क्योंकि तब कुछ बदला ही नहीं।
openedbool: क्या कोई गिना गया open दर्ज हुआ, जो `openCount` के 0 से ऊपर होने से निकाला जाता है।
clickedbool: क्या कोई गिना गया click दर्ज हुआ, जो `clickCount` के 0 से ऊपर होने से निकाला जाता है।
openCountint: वे opens जिनके बारे में माना जाता है कि वे किसी व्यक्ति के कारण हुए, संदेश की हर प्रति पर जोड़कर। स्कैनर और privacy proxies दर्ज तो होते हैं पर बाहर रखे जाते हैं, और तीस सेकंड के भीतर की दोहराई गई fetch एक में समा जाती हैं।
clickCountint: गिने गए clicks, सभी प्रतियों पर जोड़कर। इनका दोहराव प्रति संदेश नहीं बल्कि प्रति लिंक हटाया जाता है, क्योंकि कुछ सेकंड के अंतर पर दो लिंक खोलना दो कर्म हैं, दोहराव नहीं।
firstOpenAtstring or null: सभी प्रतियों में सबसे पहला गिना गया open, और कोई न होने पर null। मशीनी hits इसे कभी नहीं हिलातीं।