Python
सूची और get
`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` और `emails.list_events`।
emails.list
from openemail import openemail first = openemail.emails.list(status=['queued', 'scheduled'], from_='[email protected]', limit=50) if first['nextCursor']: second = openemail.emails.list( status=['queued', 'scheduled'], from_='[email protected]', limit=50, cursor=first['nextCursor'], )एक पेज {'items': [...], 'hasMore': ..., 'nextCursor': ...} होता है। उसके बाद वाले पेज के लिए nextCursor को उन्हीं फ़िल्टरों के साथ cursor के रूप में वापस भेजें।
emails.iterate और emails.list_all
import sys from openemail import openemail for email in openemail.emails.iterate(status='failed'): print(email['id'], email['lastError'], file=sys.stderr) failures = openemail.emails.list_all(status='failed', from_='[email protected]')दोनों आपके लिए nextCursor का अनुसरण करते हैं। iterate एक generator है जो किसी पेज को तभी लाता है जब loop वहाँ पहुँचता है, इसलिए loop से बाहर निकलने पर अनुरोध रुक जाते हैं; जबकि list_all एक list लौटाने से पहले हर पेज घूम लेता है, इसलिए इसे ऐसा फ़िल्टर दें जो ख़त्म हो। दोनों ही keyset paging करते हैं, इसलिए बीच में आया कोई संदेश इसे उस तरह कोई पंक्ति छोड़ने पर मजबूर नहीं कर सकता जैसे offset करता।
emails.get और emails.list_events
from openemail import openemail email = openemail.emails.get('msg_…')print(email['status'], email['recipients']) events = openemail.emails.list_all_events('msg_…')for event in events: print(event['type'], event['createdAt'])get अकेली ऐसी कॉल है जो recipients लौटाती है, प्रति पते एक पंक्ति। पचास संदेशों की सूची जिसमें हर एक अपने प्राप्तकर्ता ढो रहा हो, ऐसी रिपोर्ट का पेज है जो किसी ने माँगी ही नहीं।
पैरामीटर
statusEmailStatus | Sequence[EmailStatus]- एक स्थिति या कई (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), जिनमें से किसी एक से भी मेल खाना काफ़ी है। SDK list को एक ही अल्पविराम-पृथक मान के रूप में भेजता है क्योंकि सर्वर अल्पविराम पर तोड़ता है; इस समूह से बाहर का मान 422 देता है और अनजान मान का नाम लेता है।
broadcast_idstr- सिर्फ़ एक broadcast की कॉपियाँ, `broadcasts.send` से मिला एक `brd_` id। broadcast जिस भी व्यक्ति तक पहुँचता है उसे अपना संदेश मिलता है, इसलिए यह सूची दिखाती है कि यह किसे गया और हर कॉपी का क्या हुआ। `broadcasts.list_recipients` उन्हीं लोगों को उनके opens, clicks और unsubscribes के साथ सूचीबद्ध करता है।
from_str- भेजने वाले पते पर ठीक वैसा ही मिलान जैसा वह दर्ज हुआ था, यानी सादा `addr@host` छोटे अक्षरों में। पंक्ति में कोई भी प्रदर्शित नाम हटाकर लिखा जाता है, इसलिए `Acme <[email protected]>` जैसा angle-addr किसी से मेल नहीं खाएगा। तुलना से पहले आपका मान छोटे अक्षरों में बदला जाता है, और यह prefix या domain मिलान नहीं, बराबरी है। अंत का underscore इसलिए है क्योंकि `from` Python का keyword है।
limitint- इस पेज में पंक्तियाँ, 1 से 100, डिफ़ॉल्ट 25। इस सीमा से बाहर का मान clamp होने के बजाय 422 के साथ अस्वीकार होता है।
cursorstr- वह संदेश id (`msg_…`) जहाँ से पेज करना है। offset नहीं, keyset: पंक्तियाँ सख़्ती से उस संदेश के `createdAt` से पुरानी आती हैं, इसलिए बीच में आए sends किसी पंक्ति को आपसे आगे नहीं धकेल सकते। ऐसी id जो इस workspace के किसी संदेश का नाम न ले, 400 देती है।
scheduled_fromdatetime | str- केवल वे संदेश जो इस क्षण या उसके बाद के लिए शेड्यूल हैं: एक `datetime`, या समय क्षेत्र के साथ एक ISO-8601 क्षण। जिस संदेश में `scheduledAt` नहीं है वह बाहर रहता है, इसलिए `scheduled_to` और `status=['queued', 'scheduled']` के साथ यह उन संदेशों की सूची देता है जो किसी समय-खिड़की में जाने का इंतज़ार कर रहे हैं।
scheduled_todatetime | str- केवल वे संदेश जो इस क्षण या उससे पहले के लिए शेड्यूल हैं। इससे बाद का `scheduled_from` `scheduledTo` पर 422 `invalid_parameter` देता है।
प्रतिक्रिया: Page[EmailResource]
itemslist[EmailResource]- संदेशों का एक पेज, `createdAt` के अनुसार सबसे नए पहले, API के `data` लिफ़ाफ़े से निकाला हुआ। list की पंक्तियाँ प्रति-पता `recipients` विवरण कभी नहीं ढोतीं। वह `get` पर है।
hasMorebool- क्या इस पेज के आगे भी और पंक्तियाँ फ़िल्टर से मेल खाती हैं। इसका उत्तर दूसरी count query से नहीं, बल्कि `limit` से एक पंक्ति ज़्यादा लाकर दिया जाता है।
nextCursorstr | None- वह id जिसे `cursor` के रूप में वापस भेजना है, और आख़िरी पेज पर null। `iterate` और `list_all` तब रुकते हैं जब यह null हो या `hasMore` false हो, क्योंकि ऐसा पेज जो और होने का दावा करे पर कोई cursor न बताए, हमेशा के लिए घूमता रहता।
items[].objectLiteral['email']- इस सूची की पंक्ति पर हमेशा `'email'`।
items[].idstr- इस API की अपनी id, `msg_…`। बाक़ी हर emails endpoint यही लेता है, और cursor भी इसी का नाम लेता है।
items[].statusEmailStatus- संदेश अपने जीवन में कहाँ है। `partial` failed का कोई रूप नहीं बल्कि अपने आप में एक स्थिति है: कुछ प्राप्तकर्ताओं के पास वह पहुँच चुका है और उसे वापस नहीं लिया जा सकता, इसलिए दोबारा कोशिश करना ग़लत है। `bounced` का अर्थ है कि भेजे जाने के बाद वह हर प्राप्तकर्ता से बाउंस हो गया, इसलिए वह किसी के पास नहीं है, और `get` में हर प्राप्तकर्ता इसका कारण बताता है।
items[].modeApiKeyMode- `live` या `test`, उसी कुंजी से लिया गया जिसने भेजा। test send यहाँ दर्ज होता है और कभी प्रेषित नहीं होता।
items[].fromstr- वह पता जिसके तहत send अधिकृत हुआ, सादा और छोटे अक्षरों में संग्रहित, इसलिए `from` पर दिया गया प्रदर्शित नाम तार पर तो जाता है पर यहाँ नहीं रखा जाता। यह dict नहीं बल्कि सादी string है क्योंकि यही वह पहचान है जो अधिकृत हुई थी: किसी कुंजी के send scope से बाहर का पता, जो न उसके किसी domain पर हो और न उस पर नामित हो, 403 के साथ अस्वीकार होता है, चुपचाप किसी अनुमत पते से कभी नहीं बदला जाता।
items[].subjectstr | None- विषय जैसा संग्रहित है। बिना विषय दर्ज हुए संदेश पर null।
items[].messageIdstr | None- RFC 5322 Message-ID, हमारी id नहीं। MIME बनने तक null, और बाहर जाते समय sending सेवा इसे दोबारा लिख देती है, इसलिए बाद का कोई bounce या DSN अलग id ढोता है और मेल `items[].id` पर बैठाया जाता है।
items[].threadIdstr | None- वह thread जिसका यह संदेश हिस्सा है, जहाँ कोई दिया या सौंपा गया हो। अन्यथा null।
items[].transportEmailTransport | str | None- bytes कैसे रवाना हुए। dispatch तक null, और यह खुला टाइप है ताकि कोई ऐसा transport जिसका नाम यह SDK अभी नहीं लेता, breaking change न बने: संग्रहित रिकॉर्ड अब भी ऐसे transports का नाम ले सकते हैं जो अब उपयोग में नहीं हैं।
items[].attemptsint- संदेश के कितने dispatch प्रयास हो चुके हैं; पहले प्रयास से पहले 0।
items[].lastErrorstr | None- सबसे हालिया dispatch त्रुटि, किसी व्यक्ति के लिए लिखी हुई। जब तक कुछ विफल न हुआ हो तब तक null।
items[].scheduledAtstr | None- संदेश कब रवाना होना है, ISO-8601 क्षण के रूप में। null केवल ऐसे तत्काल send पर होता है जिसमें रद्द करने की खिड़की न हो: खिड़की एक छोटी देरी भर है, इसलिए `cancellableForSeconds` भी इसे भर देता है, ऐसी पंक्ति पर जिसका `status` `scheduled` नहीं बल्कि `queued` होता है।
items[].cancellableUntilstr | None- वह क्षण जब संदेश रवाना होना है; किसी भी टाले गए send पर यह `scheduledAt` जैसा ही मान रखता है और न टाले गए पर null। यह दिखाने के लिए एक timestamp है, वह परीक्षा नहीं जो सर्वर करता है: `cancel` `status` पर शाखा बनाता है, और संदेश को केवल तब तक रोकता है जब तक वह `queued` या `scheduled` हो।
items[].sentAtstr | None- वह कब गया। dispatch पूरा होने तक null, और इसीलिए शाखा इस पर नहीं बल्कि `status` पर बनानी है।
items[].tagsdict[str, str]- भेजते समय दिए गए लेबल, जस के तस लौटाए जाते हैं और कभी व्याख्या नहीं किए जाते। हमेशा एक dict (`{}` जब कोई सेट न हो, कभी null नहीं), और सिर्फ़ लौटाए जाते हैं: यह कॉल `status`, `from_`, `broadcast_id`, `scheduled_from` और `scheduled_to` पर फ़िल्टर करती है, इसलिए टैग संदेश पर पढ़ने की चीज़ है, उसे ढूँढ़ने का तरीक़ा नहीं।
items[].broadcastIdstr | None- वह `brd_` broadcast जिसकी यह संदेश एक कॉपी है, या अकेले भेजे गए संदेश के लिए null।
items[].sourceEmailSource | str- किस सतह ने send माँगा: `composer`, `api`, `mcp`, `ai`, `oauth` या `form`। `api` API कुंजी पर चलता यही क्लाइंट है, और `oauth` एक्सेस टोकन पर चलता यही क्लाइंट।
items[].createdAtstr- send का रिकॉर्ड कब लिखा गया, जो dispatch से पहले होता है। यही वह फ़ील्ड है जिससे सूची क्रम में लगती है और जिससे cursor तुलना करता है।
items[].trackingNotRequired[EmailTrackingSummary]- जुड़ाव का सारांश, केवल उसी पंक्ति पर मौजूद जिसका संदेश ट्रैक किया गया था, अन्यथा अनुपस्थित। "क्या यह ट्रैक हुआ था" का उत्तर यही अनुपस्थिति है, जबकि `openCount: 0` का पाठ होता "इसे किसी ने नहीं खोला"।
items[].tracking.opensbool- क्या यह संदेश pixel के साथ गया। यह वही है जो इस संदेश पर लागू हुआ, न कि वह जो खाता-सेटिंग अब कहती है।
items[].tracking.clicksbool- क्या इस संदेश के लिंक दोबारा लिखे गए। जब body में दोबारा लिखने लायक कोई लिंक ही न हो तब false, क्योंकि तब कुछ बदला ही नहीं गया।
items[].tracking.openedbool- क्या कोई भी गिना गया open दर्ज हुआ, जो `openCount > 0` से निकाला जाता है।
items[].tracking.clickedbool- क्या कोई भी गिना गया click दर्ज हुआ, जो `clickCount > 0` से निकाला जाता है।
items[].tracking.openCountint- वे opens जिनके बारे में माना जाता है कि वे किसी व्यक्ति के कारण हुए, संदेश की हर प्रति पर जोड़कर। स्कैनर और privacy proxies दर्ज तो होते हैं पर बाहर रखे जाते हैं, और तीस सेकंड के भीतर की दोहराई गई fetch एक में समा जाती हैं।
items[].tracking.clickCountint- गिने गए clicks, सभी प्रतियों पर जोड़कर। इनका दोहराव प्रति संदेश नहीं बल्कि प्रति लिंक हटाया जाता है, क्योंकि कुछ सेकंड के अंतर पर दो लिंक खोलना दो कर्म हैं, दोहराव नहीं।
items[].tracking.firstOpenAtstr | None- सभी प्रतियों में सबसे पहला गिना गया open, और कोई न होने पर null। मशीनी hits इसे कभी नहीं हिलातीं।
items[].translationNotRequired[EmailTranslationResource]- list की पंक्ति पर कभी मौजूद नहीं: अनुवाद का रिकॉर्ड संग्रहित रिक्वेस्ट में रहता है, जिसे list जानबूझकर नहीं लाती। यहाँ इसकी अनुपस्थिति इस बारे में कुछ नहीं कहती कि संदेश अनूदित हुआ था या नहीं। `get` से पूछें।