डोमेन
`domains.list`, `get` और `update`।
हर method
const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })प्राप्त करना और भेजना दो स्वतंत्र तथ्य हैं और दो ऑब्जेक्ट के रूप में लौटाए जाते हैं। receiving.verified का अर्थ है कि domain का MX उसकी मेल यहाँ लाता है और उसकी स्वामित्व चुनौती प्रकाशित है। sending बाहर जाने वाली signing जाँच बताता है: status verified, pending, failed, no_identity या unknown होता है, और canSend बताता है कि इस domain से भेजना अभी स्वीकार होगा या नहीं। एक दिन से पुराना नकारात्मक निर्णय इनकार नहीं, अज्ञात माना जाता है, इसलिए status के बजाय canSend पर शाखा बनाएँ।
update domain का custom tracking domain — जैसे links.acme.com जैसा कोई subdomain — सेट करता है, दोबारा जाँचता है या हटाता है, और वही DomainDetailResource लौटाता है जो get लौटाता है। tracking हर पढ़ाई पर इसकी जानकारी देता है। जब तक कोई जाँच पास नहीं होती, tracking.status pending रहता है और ट्रैक किए गए लिंक तथा open pixel डिफ़ॉल्ट OpenEmail होस्ट का ही उपयोग करते रहते हैं। एक बार जाँच पास हो जाने पर यह active हो जाता है और domain से जाने वाली नई मेल दोनों के लिए tracking domain का उपयोग करती है।
get domain के पतों की सूची भी देता है। addresses.list() उससे जुड़ी कॉल है: हर वह पता जिसे यह कुंजी From header में रख सकती है, जो इससे संकरा दायरा है।
पैरामीटर: domains.get
domainIdstringआवश्यक- `domains.list` से मिली id — domain जोड़े जाने पर बनी एक UUID, होस्टनाम नहीं, इसलिए `get('example.com')` को कुछ नहीं मिलेगा। खोज id के साथ-साथ कुंजी के अपने connection तक सीमित है, इसलिए किसी दूसरे workspace का domain 403 नहीं, 404 होता है।
पैरामीटर: domains.update
idstringआवश्यक- वही domain id जो `get` लेता है। इसके लिए ज़रूरी scope `domains:write` है।
patch.trackingHoststring | nullआवश्यक- domain का कोई subdomain, अधिकतम 512 वर्ण, जैसे `links.acme.com`। इसे trim करके छोटे अक्षरों में बदला जाता है, और आगे लगा `https://` या `http://`, कोई path और अंत का बिंदु हटा दिए जाते हैं। नया मान उसी कॉल में जाँचा, सहेजा और परखा जाता है। जो मान domain के पास पहले से है उस पर जाँच दोबारा चलती है, बशर्ते पिछली जाँच को 30 सेकंड से कम न हुआ हो। `null` या खाली स्ट्रिंग tracking domain हटा देती है।
अस्वीकृत होस्ट param में trackingHost का नाम लेता हुआ एक OpenEmailApiError फेंकता है: ऐसे नाम के लिए जो इस्तेमाल नहीं हो सकता — जैसे domain के बाहर का कोई नाम — 422 invalid_tracking_host; नए होस्ट के लिए तब 409 domain_not_verified जब receiving.verified false है और domain का _openemail-challenge TXT रिकॉर्ड अभी प्रकाशित नहीं हुआ; और ऐसे नाम के लिए 409 tracking_host_in_use जिसे कोई दूसरा domain पहले से इस्तेमाल कर रहा है, या जब tracking domain किसी दूसरे OpenEmail सर्वर द्वारा प्रबंधित हो। कुछ ख़ास पतों तक सीमित कुंजी को 422 capability_unsupported मिलता है, क्योंकि tracking domain domain के हर पते पर लागू होता है।
प्रतिक्रिया: DomainDetailResource
object'domain'- हमेशा स्ट्रिंग `domain`, `list` की पंक्तियों पर भी और इस पर भी।
idstring- domain की UUID। पंक्ति के पूरे जीवन के लिए स्थिर, और यही वह एकमात्र handle है जिसे बाक़ी domain कॉल स्वीकार करती हैं।
domainstring- सादा होस्टनाम, छोटे अक्षरों में: `example.com`। पूरे उत्पाद में अद्वितीय, हर domain का एक ही मालिक, इसलिए दो workspaces एक ही domain पर दावा नहीं कर सकते।
receiving.verifiedboolean- तब true जब DNS ने दिखा दिया कि domain का MX ऐसे होस्ट का नाम ले रहा है जो उसकी मेल यहाँ लाता है, और जहाँ पंक्ति में चुनौती टोकन है वहाँ उससे मेल खाता `_openemail-challenge` TXT रिकॉर्ड भी मिल गया। अकेला MX कुछ भी साबित नहीं करता, क्योंकि जिन सब domains के लिए हम मेल लेते हैं वे सभी वही होस्टनाम प्रकाशित करते हैं — इसीलिए टोकन है, और इसीलिए यही ध्वज वह द्वार है जिसे inbound डिलीवरी मेल स्वीकार करने से पहले जाँचती है।
receiving.verifiedAtstring | null- सत्यापन कब पास हुआ, ISO-8601 में। जब तक नहीं हुआ तब तक null, और `verified` ठीक इसी column से निकाला जाता है, इसलिए दोनों कभी असहमत नहीं हो सकते।
receiving.catchAllboolean- कोई भी local-part स्वीकार किया जाए या नहीं। जब से यह नियम बना है तब से जोड़े गए domains पर यह डिफ़ॉल्ट रूप से चालू है; इसके बंद होने पर केवल domain पर नामित पते ही स्वीकार होते हैं और बाक़ी SMTP के समय ही अस्वीकार कर दिए जाते हैं, जिससे भेजने वाले को चुप्पी के बजाय bounce मिलता है।
receiving.lastCheckedAtstring | null- इस domain के बारे में DNS से आख़िरी बार कब पूछा गया। null का अर्थ है कभी देखा ही नहीं, जो एक मिनट पहले domain जोड़ने वाले के लिए जाँच की विफलता से बहुत अलग बात है। यह endpoint संग्रहित परिणाम बताता है, अपनी ओर से कभी कोई जाँच नहीं चलाता।
receiving.errorstring | null- आख़िरी जाँच क्यों पास नहीं हुई, ऐसे शब्दों में जिन पर मालिक कार्रवाई कर सके: `No MX records yet. DNS changes can take a few minutes to spread.` एक आम उदाहरण है। पास हो जाने पर null, और यह निकाला हुआ नहीं बल्कि संग्रहित होता है ताकि दोबारा लोड करने पर और निर्धारित पुनः-जाँच पर एक ही बात कही जाए।
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown'- आख़िरी जाँच ने बाहर जाने वाली signing स्थिति जैसी देखी। यह इसी रिक्वेस्ट पर परखी नहीं जाती बल्कि संग्रहित जाँच से पढ़ी जाती है, इसलिए `sending.checkedAt` बताता है कि वह कितनी पुरानी है।
sending.canSendboolean- इस domain से भेजना अभी स्वीकार होगा या नहीं। एक दिन से पुराना नकारात्मक निर्णय इनकार नहीं, अज्ञात माना जाता है, इसलिए यह true हो सकता है जबकि `status` `pending` हो। भेजने से पहले इसी पर शाखा बनाएँ: इसका false होना यानी इस domain से `emails.send` 409 `domain_not_sendable` के साथ अस्वीकार होगा।
sending.checkedAtstring | null- signing स्थिति की आख़िरी जाँच कब हुई, ISO-8601 में। null का अर्थ है कभी नहीं, जो किसी विफलता से बहुत अलग बात है।
sending.errorstring | null- आख़िरी signing विफलता शब्दों में, या पास हो जाने पर null।
sending.notestring- पाँच वाक्यों में से एक, जिसे `sending.status` चुनता है, और जो उस स्थिति का अर्थ ऐसे शब्दों में बताता है जिन पर domain का मालिक कार्रवाई कर सके। यह किसी व्यक्ति के पढ़ने के लिए लिखा गद्य है। इस पर नहीं, `sending.canSend` पर शाखा बनाएँ।
trackingDomainTracking- domain का custom tracking domain, `list` की पंक्तियों पर भी और इस पर भी, और यही वह चीज़ है जिसे `update` बदलता है।
tracking.hoststring | null- tracking domain, जैसे `links.acme.com`, या कोई सेट न होने पर null।
tracking.status'none' | 'pending' | 'active' | 'failed'- `none` का अर्थ है कोई tracking domain सेट नहीं है, `pending` का अर्थ है वह कभी कोई जाँच पास नहीं कर सका, `active` का अर्थ है नई मेल उसका उपयोग करती है, और `failed` का अर्थ है वह पहले पास हुआ था और तब से उपयोग से बाहर हो गया। कोई सक्रिय होस्ट लगातार तीन जाँच विफल होने पर, या उसकी आख़िरी पास हुई जाँच के 2 घंटे से ज़्यादा पुराना हो जाने पर उपयोग से बाहर हो जाता है।
tracking.activeboolean- ठीक तभी true जब `status` `active` हो, यानी जब domain से जाने वाली नई मेल के ट्रैक किए गए लिंक और open pixel उस होस्ट का उपयोग करते हों।
tracking.targetstring- वह पता जिस पर CNAME रिकॉर्ड इशारा करता है, सिर्फ़ इसी tracking domain के लिए तैयार किया गया। जब तक `host` null है और जब तक नए होस्ट का पता तैयार हो रहा है, तब तक खाली स्ट्रिंग।
tracking.record{ type: 'CNAME'; name: string; value: string } | null- प्रकाशित करने योग्य रिकॉर्ड, जिसका नाम `host` के अनुसार है और मान `target`। जब कोई tracking domain न हो तब null, और तब तक भी null जब तक नए होस्ट का पता तैयार हो रहा हो।
tracking.checkedAtstring | null- होस्ट की आख़िरी जाँच कब हुई, ISO-8601 में। पहली जाँच तक null।
tracking.verifiedAtstring | null- कोई जाँच आख़िरी बार कब पास हुई, ISO-8601 में। जिस होस्ट ने कभी कोई जाँच पास नहीं की उसके लिए null।
tracking.errorstring | null- आख़िरी जाँच में क्या मिला, ऐसे शब्दों में जिन पर domain का मालिक कार्रवाई कर सके। जब आख़िरी जाँच पास हो गई हो या अभी कोई जाँच चली ही न हो तब null। एक या दो जाँच विफल कर चुका होस्ट अब भी `active` रहता है और कारण यहीं रखता है।
addressesArray<{ address: string; enabled: boolean }>- domain की हर पता-पंक्ति, और यही वह चीज़ है जो `get` किसी `list` पंक्ति के मुक़ाबले जोड़ता है। इसमें वे पंक्तियाँ भी शामिल हैं जो डिलीवरी ने catch-all के तहत ख़ुद लिखीं, और catch-all बंद होते ही वे स्वीकार होना बंद हो जाती हैं, इसलिए यह array इस बात की सूची नहीं है कि कौन मेल पाएगा।
addresses[].addressstring- पूरा पता, संग्रहित local-part और होस्टनाम से दोबारा बनाया गया और छोटे अक्षरों में, ताकि वह ऊपर के `domain` से भटकने के बजाय हमेशा उससे मेल खाए।
addresses[].enabledboolean- false पते को निष्क्रिय कर देता है, और निष्क्रिय पता catch-all चालू होने पर भी अस्वीकार होता है। हर पंक्ति दोनों ही हालत में सूचीबद्ध रहती है, इसलिए इस array को काम कर रहे पतों का समूह मानने के बजाय इसी पर फ़िल्टर करें।
createdAtstring- domain की पंक्ति कब जोड़ी गई, ISO-8601 में। यह नहीं कि वह कब सत्यापित हुई: वह `receiving.verifiedAt` है, जो इसके सेट होने पर भी null हो सकता है।