Ruby

सूची और get

`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` और `emails.list_events`।

emails.list

list_emails.rb

filters = {status: ["queued", "scheduled"], from: "[email protected]"} first = client.emails.list(**filters, limit: 50)second = client.emails.list(**filters, limit: 50, cursor: first.next_cursor) if first.next_cursor p first.items.size, second&.items&.size

एक पेज items, has_more? और next_cursor वाला OpenEmail::Page होता है। उसके बाद वाले पेज के लिए next_cursor को उन्हीं फ़िल्टरों के साथ cursor: के रूप में वापस भेजें।

emails.iterate और emails.list_all

iterate_emails.rb

client.emails.iterate(status: "failed") do |email|  warn "#{email[:id]} #{email[:lastError]}"end failures = client.emails.list_all(status: "failed", from: "[email protected]")puts failures.size

दोनों आपके लिए next_cursor का पीछा करते हैं। iterate कोई पेज तभी लाता है जब चलना उस तक पहुँचे, इसलिए block में break, या block के बिना लौटे Enumerator पर first या find, रिक्वेस्ट रोक देता है, जबकि list_all एक Array लौटाने से पहले हर पेज पर चलता है, इसलिए उसे ऐसा फ़िल्टर दें जो ख़त्म हो। दोनों ही तरह keyset पेजिंग है, इसलिए बीच में आया संदेश इससे कोई पंक्ति नहीं छुड़वा सकता, जैसा offset के साथ होता।

emails.get और emails.list_events

get_email.rb

email = client.emails.get("msg_3f9a1c07d2b84e6a9c5b1f20")puts email[:status]p email[:recipients] events = client.emails.list_all_events("msg_3f9a1c07d2b84e6a9c5b1f20")events.each { |event| puts "#{event[:type]} #{event[:createdAt]}" }

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

list_events एक send के इवेंट का सिलसिला पढ़ता है, सबसे पुराना पहले: email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened और बाक़ी, हर एक एक data Hash के साथ जिसका आकार उसके type पर निर्भर करता है। list_all_events और iterate_events आपके लिए पूरे सिलसिले पर चलते हैं। वेबहुक इन्हीं इवेंट का एक हिस्सा घटते समय पहुँचाते हैं, इसलिए जब कोई वेबहुक छूट जाए तो यहीं देखें।

पैरामीटर

statusString or Array<String>: एक status या कई (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), जो दिए गए किसी भी एक से मेल खाता है। `bounced` का मतलब है कि संदेश जिन प्राप्तकर्ताओं को गया उन सभी के लिए bounce हुआ, जबकि जो संदेश कुछ के लिए bounce हुआ और बाक़ी तक पहुँचा वह `partial` पढ़ता है। gem Array को कॉमा से अलग एक मान के रूप में भेजता है क्योंकि सर्वर कॉमा पर बाँटता है, और सेट से बाहर का मान अज्ञात वाले का नाम लेता 422 है।
broadcast_idString: सिर्फ़ एक ब्रॉडकास्ट की कॉपियाँ, `broadcasts.send` से मिली `brd_` id। ब्रॉडकास्ट जिस भी व्यक्ति तक पहुँचता है उसे अपना अलग संदेश मिलता है, इसलिए यह बताता है कि यह किन्हें गया और हर कॉपी के साथ क्या हुआ। `broadcasts.list_recipients` इन्हीं लोगों को उनके opens, clicks और unsubscribes के साथ सूचीबद्ध करता है।
fromString: भेजने वाले पते पर सटीक मिलान, जैसा वह दर्ज हुआ था, यानी छोटे अक्षरों में सादा `addr@host`। पंक्ति हर display name हटाकर लिखी जाती है, इसलिए `Acme <[email protected]>` जैसा angle-addr किसी से मेल नहीं खाता। तुलना से पहले आपका मान छोटे अक्षरों में बदला जाता है, और यह बराबरी है, prefix या डोमेन मिलान नहीं।
scheduled_fromTime, DateTime or String: सिर्फ़ वे संदेश जो इस क्षण या बाद के लिए शेड्यूल हैं। `scheduled_to:` और `status: ["scheduled", "queued"]` के साथ यह बताता है कि किसी समय-सीमा में क्या जाने का इंतज़ार कर रहा है, जैसा ऐप का कैलेंडर करता है। जिस संदेश में `scheduledAt` नहीं है उसे छोड़ दिया जाता है। Time, DateTime या offset के साथ ISO 8601 क्षण पास करें: Ruby Date सादी तारीख़ के रूप में भेजी जाती है, जिसे ये दोनों फ़िल्टर अस्वीकार करते हैं।
scheduled_toTime, DateTime or String: सिर्फ़ वे संदेश जो इस क्षण या पहले के लिए शेड्यूल हैं। `scheduled_to:` के बाद का `scheduled_from:` 422 `invalid_parameter` है।
limitInteger: इस पेज की पंक्तियाँ, 1 से 100, डिफ़ॉल्ट 25। उस सीमा से बाहर का मान सीमा में काटे जाने के बजाय 422 के रूप में अस्वीकार होता है। `list_all` और `iterate` पर यह उनके लाए हर पेज का आकार है।
cursorString: जिस संदेश id (`msg_…`) से पेजिंग करनी है। offset नहीं, keyset: पंक्तियाँ उस संदेश के `createdAt` से सख़्ती से पुरानी लौटती हैं, इसलिए पेज के बीच आए sends कोई पंक्ति आपसे आगे नहीं धकेल सकते। जो id इस वर्कस्पेस के किसी संदेश का नाम नहीं लेती वह 400 `invalid_cursor` है।
api_keyString: क्लाइंट की कुंजी के बजाय इस कुंजी से सूची लेता है।

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

जवाब: OpenEmail::Page

itemsArray<Hash>: संदेशों का एक पेज, `createdAt` के अनुसार सबसे नए पहले, API के `data` लिफ़ाफ़े से निकाला हुआ। list की पंक्तियाँ प्रति-पता `recipients` विवरण कभी नहीं ढोतीं। वह `get` पर है।
has_more?Boolean: क्या इस पेज के आगे भी और पंक्तियाँ फ़िल्टर से मेल खाती हैं। इसका उत्तर दूसरी count query से नहीं, बल्कि `limit` से एक पंक्ति ज़्यादा लाकर दिया जाता है।
next_cursorString or nil: वह id जिसे `cursor:` के रूप में वापस भेजना है, और आख़िरी पेज पर nil। जब यह nil हो या `has_more?` false हो तो `iterate` और `list_all` रुक जाते हैं, क्योंकि जो पेज और होने का दावा करे पर कोई cursor न बताए वह हमेशा लूप में घूमता रहता।

हर आइटम

objectString: इस सूची की पंक्ति पर हमेशा `email`।
idString: इस API की अपनी id, `msg_…`। बाक़ी हर emails कॉल यही लेती है, और cursor भी इसी का नाम लेता है।
statusString: संदेश अपने जीवन में कहाँ है। `partial` failed का कोई रूप नहीं बल्कि अपने आप में एक स्थिति है: कुछ प्राप्तकर्ताओं के पास वह पहुँच चुका है और उसे वापस नहीं लिया जा सकता, इसलिए दोबारा कोशिश करना ग़लत है। `bounced` का अर्थ है कि भेजे जाने के बाद वह हर प्राप्तकर्ता से बाउंस हो गया, इसलिए वह किसी के पास नहीं है, और `get` में हर प्राप्तकर्ता इसका कारण बताता है।
modeString: `live` या `test`, उसी कुंजी से लिया गया जिसने भेजा। test send यहाँ दर्ज होता है और कभी प्रेषित नहीं होता।
fromString: वह पता जिसके तहत send की अनुमति मिली, सादे और छोटे अक्षरों में सहेजा गया, इसलिए `from` पर दिया गया display name नेटवर्क पर तो जाता है पर यहाँ नहीं रखा जाता। Hash के बजाय सादी String, क्योंकि यही वह पहचान है जिसे अनुमति मिली: कुंजी के send scope से बाहर का पता, जो न उसके डोमेन पर है न उस पर नाम से दर्ज है, 403 के साथ अस्वीकार होता है, और कभी चुपचाप किसी अनुमत पते से नहीं बदला जाता।
subjectString or nil: विषय, जैसा सहेजा गया। बिना विषय के दर्ज संदेश पर nil।
messageIdString or nil: RFC 5322 Message-ID, हमारी id नहीं। MIME बनने तक nil, और भेजने वाली सेवा बाहर जाते समय इसे दोबारा लिखती है, इसलिए बाद का कोई bounce या DSN अलग id लिए आता है और इसकी जगह `id` से मिलाया जाता है।
threadIdString or nil: वह थ्रेड जिसका यह संदेश हिस्सा है, जहाँ कोई दिया या निर्धारित किया गया हो। वरना nil।
transportString or nil: बाइट्स कैसे निकले। भेजे जाने तक nil। सहेजे गए रिकॉर्ड में ऐसे transport के नाम भी हो सकते हैं जो अब इस्तेमाल में नहीं हैं, इसलिए जिस मान को आप नहीं जानते उसे error नहीं, जानकारी मानें।
attemptsInteger: संदेश के कितने dispatch प्रयास हो चुके हैं; पहले प्रयास से पहले 0।
lastErrorString or nil: भेजने की सबसे हाल की error, किसी व्यक्ति के लिए लिखी गई। जब तक कुछ विफल न हुआ हो तब तक nil।
scheduledAtString or nil: संदेश कब निकलना है, ISO 8601 क्षण के रूप में। सिर्फ़ बिना रद्द-विंडो वाले तुरंत send पर nil: विंडो एक छोटी देरी के सिवा कुछ नहीं, इसलिए `cancellableForSeconds` भी इसे भर देता है, उस पंक्ति पर जिसका `status` `scheduled` के बजाय `queued` है।
cancellableUntilString or nil: वह क्षण जब संदेश को निकलना है, किसी भी टाले गए send पर `scheduledAt` जैसा ही मान, और न टाले गए पर nil। यह दिखाने के लिए एक timestamp है, सर्वर की जाँच नहीं: `cancel` `status` पर शाखा बनाता है, और संदेश को तभी रोकता है जब वह अभी भी `queued` या `scheduled` हो।
sentAtString or nil: यह कब गया। भेजना पूरा होने तक nil, इसीलिए शाखा इस पर नहीं, `status` पर बनानी है।
tagsHash: send पर दिए गए लेबल, वापस लौटाए जाते हैं और इनकी कभी व्याख्या नहीं होती। हमेशा एक Hash, कुछ सेट न हो तो ख़ाली, कभी nil नहीं, और सिर्फ़ लौटाए जाते हैं: यह सूची `status`, `from`, `broadcast_id` और शेड्यूल विंडो पर फ़िल्टर करती है, इसलिए टैग संदेश से पढ़ने की चीज़ है, उसे ढूँढने का तरीका नहीं।
broadcastIdString or nil: वह `brd_` ब्रॉडकास्ट जिसकी यह संदेश एक कॉपी है, या अपने आप भेजे गए संदेश के लिए nil।
sourceString: किस सतह ने send माँगा: `composer`, `api`, `mcp`, `ai` या `queue`। `api` यही क्लाइंट है।
createdAtString: send का रिकॉर्ड कब लिखा गया, जो dispatch से पहले होता है। यही वह फ़ील्ड है जिससे सूची क्रम में लगती है और जिससे cursor तुलना करता है।
trackingHash: engagement का सारांश, सिर्फ़ उस पंक्ति पर मौजूद जिसका संदेश ट्रैक हुआ, वरना अनुपस्थित। “क्या यह ट्रैक हुआ” का जवाब इसका न होना है, जबकि `openCount` का 0 होना “किसी ने नहीं खोला” पढ़ा जाता।
translationHash: list की पंक्ति पर कभी मौजूद नहीं: अनुवाद का रिकॉर्ड संग्रहित रिक्वेस्ट में रहता है, जिसे list जानबूझकर नहीं लाती। यहाँ इसकी अनुपस्थिति इस बारे में कुछ नहीं कहती कि संदेश अनूदित हुआ था या नहीं। `get` से पूछें।

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

opensBoolean: क्या यह संदेश pixel के साथ गया। यह वही है जो इस संदेश पर लागू हुआ, न कि वह जो खाता-सेटिंग अब कहती है।
clicksBoolean: क्या इस संदेश के लिंक दोबारा लिखे गए। जब बॉडी में दोबारा लिखने को कोई लिंक न हो तो false, क्योंकि तब कुछ बदला ही नहीं।
openedBoolean: क्या कोई गिना गया open दर्ज हुआ, जो `openCount` के 0 से ऊपर होने से निकाला जाता है।
clickedBoolean: क्या कोई गिना गया click दर्ज हुआ, जो `clickCount` के 0 से ऊपर होने से निकाला जाता है।
openCountInteger: वे opens जिनके बारे में माना जाता है कि वे किसी व्यक्ति के कारण हुए, संदेश की हर प्रति पर जोड़कर। स्कैनर और privacy proxies दर्ज तो होते हैं पर बाहर रखे जाते हैं, और तीस सेकंड के भीतर की दोहराई गई fetch एक में समा जाती हैं।
clickCountInteger: गिने गए clicks, सभी प्रतियों पर जोड़कर। इनका दोहराव प्रति संदेश नहीं बल्कि प्रति लिंक हटाया जाता है, क्योंकि कुछ सेकंड के अंतर पर दो लिंक खोलना दो कर्म हैं, दोहराव नहीं।
firstOpenAtString or nil: कॉपियों में सबसे पहला गिना गया open, और जब तक कोई न हो तब तक nil। मशीनी hits इसे कभी नहीं खिसकाते।