SDK
सूची और get
`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` और `emails.listEvents`।
emails.list
const first = await openemail.emails.list({ status: ['queued', 'scheduled'], from: '[email protected]', limit: 50,}) const second = first.nextCursor ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor }) : nullएक पेज { items, hasMore, nextCursor } होता है। उसके बाद वाले पेज के लिए nextCursor को उन्हीं फ़िल्टरों के साथ cursor के रूप में वापस भेजें।
emails.iterate और emails.listAll
for await (const email of openemail.emails.iterate({ status: 'failed' })) { console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })दोनों आपके लिए nextCursor का अनुसरण करते हैं। iterate किसी पेज को तभी लाता है जब loop वहाँ पहुँचता है, इसलिए loop से बाहर निकलने पर रिक्वेस्ट रुक जाती हैं; जबकि listAll एक array में resolve होने से पहले हर पेज घूम लेता है, इसलिए इसे ऐसा फ़िल्टर दें जो ख़त्म हो। दोनों ही keyset paging करते हैं, इसलिए बीच में आया कोई संदेश इसे उस तरह कोई पंक्ति छोड़ने पर मजबूर नहीं कर सकता जैसे offset करता।
emails.get और emails.listEvents
const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)get अकेली ऐसी कॉल है जो recipients लौटाती है, प्रति पते एक पंक्ति। पचास संदेशों की सूची जिसमें हर एक अपने प्राप्तकर्ता ढो रहा हो, ऐसी रिपोर्ट का पेज है जो किसी ने माँगी ही नहीं।
पैरामीटर
statusEmailStatus | EmailStatus[]- एक स्थिति या कई (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), जिनमें से किसी एक से भी मेल खाना काफ़ी है। SDK array को एक ही अल्पविराम-पृथक मान के रूप में भेजता है क्योंकि सर्वर अल्पविराम पर तोड़ता है; इस समूह से बाहर का मान 422 देता है और अनजान मान का नाम लेता है।
fromstring- भेजने वाले पते पर ठीक वैसा ही मिलान जैसा वह दर्ज हुआ था, यानी सादा `addr@host` छोटे अक्षरों में। पंक्ति में कोई भी प्रदर्शित नाम हटाकर लिखा जाता है, इसलिए `Acme <[email protected]>` जैसा angle-addr किसी से मेल नहीं खाएगा। तुलना से पहले आपका मान छोटे अक्षरों में बदला जाता है, और यह prefix या domain मिलान नहीं, बराबरी है।
limitnumber- इस पेज में पंक्तियाँ, 1 से 100, डिफ़ॉल्ट 25। इस सीमा से बाहर का मान clamp होने के बजाय 422 के साथ अस्वीकार होता है।
cursorstring- वह संदेश id (`msg_…`) जहाँ से पेज करना है। offset नहीं, keyset: पंक्तियाँ सख़्ती से उस संदेश के `createdAt` से पुरानी आती हैं, इसलिए बीच में आए sends किसी पंक्ति को आपसे आगे नहीं धकेल सकते। ऐसी id जो इस workspace के किसी संदेश का नाम न ले, 400 देती है।
प्रतिक्रिया: Page<EmailResource>
itemsEmailResource[]- संदेशों का एक पेज, `createdAt` के अनुसार सबसे नए पहले, API के `data` लिफ़ाफ़े से निकाला हुआ। list की पंक्तियाँ प्रति-पता `recipients` विवरण कभी नहीं ढोतीं। वह `get` पर है।
hasMoreboolean- क्या इस पेज के आगे भी और पंक्तियाँ फ़िल्टर से मेल खाती हैं। इसका उत्तर दूसरी count query से नहीं, बल्कि `limit` से एक पंक्ति ज़्यादा लाकर दिया जाता है।
nextCursorstring | null- वह id जिसे `cursor` के रूप में वापस भेजना है, और आख़िरी पेज पर null। `iterate` और `listAll` तब रुकते हैं जब यह null हो या `hasMore` false हो, क्योंकि ऐसा पेज जो और होने का दावा करे पर कोई cursor न बताए, हमेशा के लिए घूमता रहता।
items[].object'email'- इस सूची की पंक्ति पर हमेशा `'email'`।
items[].idstring- इस API की अपनी id, `msg_…`। बाक़ी हर emails endpoint यही लेता है, और cursor भी इसी का नाम लेता है।
items[].statusEmailStatus- संदेश अपने जीवन में कहाँ है। `partial` failed का कोई रूप नहीं बल्कि अपने आप में एक स्थिति है: कुछ प्राप्तकर्ताओं के पास वह पहुँच चुका है और उसे वापस नहीं लिया जा सकता, इसलिए दोबारा कोशिश करना ग़लत है।
items[].modeApiKeyMode- `live` या `test`, उसी कुंजी से लिया गया जिसने भेजा। test send यहाँ दर्ज होता है और कभी प्रेषित नहीं होता।
items[].fromstring- वह पता जिसके तहत send अधिकृत हुआ, सादा और छोटे अक्षरों में संग्रहित, इसलिए `from` पर दिया गया प्रदर्शित नाम तार पर तो जाता है पर यहाँ नहीं रखा जाता। यह ऑब्जेक्ट नहीं बल्कि सादी स्ट्रिंग है क्योंकि यही वह पहचान है जो अधिकृत हुई थी: किसी कुंजी के send scope से बाहर का पता — जो न उसके किसी domain पर हो और न उस पर नामित हो — 403 के साथ अस्वीकार होता है, चुपचाप किसी अनुमत पते से कभी नहीं बदला जाता।
items[].subjectstring | null- विषय जैसा संग्रहित है। बिना विषय दर्ज हुए संदेश पर null।
items[].messageIdstring | null- RFC 5322 Message-ID, हमारी id नहीं। MIME बनने तक null, और बाहर जाते समय sending सेवा इसे दोबारा लिख देती है, इसलिए बाद का कोई bounce या DSN अलग id ढोता है और मेल `items[].id` पर बैठाया जाता है।
items[].threadIdstring | null- वह thread जिसका यह संदेश हिस्सा है, जहाँ कोई दिया या सौंपा गया हो। अन्यथा null।
items[].transportEmailTransport | (string & {}) | null- bytes कैसे रवाना हुए। dispatch तक null, और यह खुला टाइप है ताकि कोई ऐसा transport जिसका नाम यह SDK अभी नहीं लेता, breaking change न बने: संग्रहित रिकॉर्ड अब भी ऐसे transports का नाम ले सकते हैं जो अब उपयोग में नहीं हैं।
items[].attemptsnumber- संदेश के कितने dispatch प्रयास हो चुके हैं; पहले प्रयास से पहले 0।
items[].lastErrorstring | null- सबसे हालिया dispatch त्रुटि, किसी व्यक्ति के लिए लिखी हुई। जब तक कुछ विफल न हुआ हो तब तक null।
items[].scheduledAtstring | null- संदेश कब रवाना होना है, ISO-8601 क्षण के रूप में। null केवल ऐसे तत्काल send पर होता है जिसमें रद्द करने की खिड़की न हो: खिड़की एक छोटी देरी भर है, इसलिए `cancellableForSeconds` भी इसे भर देता है — ऐसी पंक्ति पर जिसका `status` `scheduled` नहीं बल्कि `queued` होता है।
items[].cancellableUntilstring | null- वह क्षण जब संदेश रवाना होना है; किसी भी टाले गए send पर यह `scheduledAt` जैसा ही मान रखता है और न टाले गए पर null। यह दिखाने के लिए एक timestamp है, वह परीक्षा नहीं जो सर्वर करता है: `cancel` `status` पर शाखा बनाता है, और संदेश को केवल तब तक रोकता है जब तक वह `queued` या `scheduled` हो।
items[].sentAtstring | null- वह कब गया। dispatch पूरा होने तक null, और इसीलिए शाखा इस पर नहीं बल्कि `status` पर बनानी है।
items[].tagsRecord<string, string>- send पर दिए गए लेबल, वापस लौटाए हुए और कभी व्याख्या न किए हुए। यह हमेशा एक ऑब्जेक्ट होता है (कोई सेट न होने पर `{}`, कभी null नहीं), और केवल लौटाया जाता है: यह endpoint `status` और `from` पर फ़िल्टर करता है, इसलिए tag संदेश ढूँढ़ने का तरीक़ा नहीं बल्कि संदेश से पढ़ने की चीज़ है।
items[].sourceEmailSource- किस सतह ने send माँगा: `composer`, `api`, `mcp`, `ai` या `queue`। `api` यही क्लाइंट है।
items[].createdAtstring- send का रिकॉर्ड कब लिखा गया, जो dispatch से पहले होता है। यही वह फ़ील्ड है जिससे सूची क्रम में लगती है और जिससे cursor तुलना करता है।
items[].trackingEmailTrackingSummary- जुड़ाव का सारांश, केवल उसी पंक्ति पर मौजूद जिसका संदेश ट्रैक किया गया था, अन्यथा अनुपस्थित। "क्या यह ट्रैक हुआ था" का उत्तर यही अनुपस्थिति है, जबकि `openCount: 0` का पाठ होता "इसे किसी ने नहीं खोला"।
items[].tracking.opensboolean- क्या यह संदेश pixel के साथ गया। यह वही है जो इस संदेश पर लागू हुआ, न कि वह जो खाता-सेटिंग अब कहती है।
items[].tracking.clicksboolean- क्या इस संदेश के लिंक दोबारा लिखे गए। जब body में दोबारा लिखने लायक कोई लिंक ही न हो तब false, क्योंकि तब कुछ बदला ही नहीं गया।
items[].tracking.openedboolean- क्या कोई भी गिना गया open दर्ज हुआ, जो `openCount > 0` से निकाला जाता है।
items[].tracking.clickedboolean- क्या कोई भी गिना गया click दर्ज हुआ, जो `clickCount > 0` से निकाला जाता है।
items[].tracking.openCountnumber- वे opens जिनके बारे में माना जाता है कि वे किसी व्यक्ति के कारण हुए, संदेश की हर प्रति पर जोड़कर। स्कैनर और privacy proxies दर्ज तो होते हैं पर बाहर रखे जाते हैं, और तीस सेकंड के भीतर की दोहराई गई fetch एक में समा जाती हैं।
items[].tracking.clickCountnumber- गिने गए clicks, सभी प्रतियों पर जोड़कर। इनका दोहराव प्रति संदेश नहीं बल्कि प्रति लिंक हटाया जाता है, क्योंकि कुछ सेकंड के अंतर पर दो लिंक खोलना दो कर्म हैं, दोहराव नहीं।
items[].tracking.firstOpenAtstring | null- सभी प्रतियों में सबसे पहला गिना गया open, और कोई न होने पर null। मशीनी hits इसे कभी नहीं हिलातीं।
items[].translationEmailTranslationResource- list की पंक्ति पर कभी मौजूद नहीं: अनुवाद का रिकॉर्ड संग्रहित रिक्वेस्ट में रहता है, जिसे list जानबूझकर नहीं लाती। यहाँ इसकी अनुपस्थिति इस बारे में कुछ नहीं कहती कि संदेश अनूदित हुआ था या नहीं। `get` से पूछें।