डोमेन
`domains.list`, `list_all`, `iterate`, `get` और `update`।
हर मेथड
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"endप्राप्त करना और भेजना दो स्वतंत्र तथ्य हैं और दो Hashes के रूप में लौटाए जाते हैं। receiving.verified का मतलब है कि डोमेन का MX उसका मेल यहाँ लाता है और उसका स्वामित्व challenge प्रकाशित है। sending बाहर जाने वाली signing जाँच बताता है: status verified, pending, failed, no_identity या unknown है, और canSend बताता है कि डोमेन से भेजा गया send अभी स्वीकार होगा या नहीं। एक दिन से पुराना नकारात्मक फ़ैसला अस्वीकार नहीं, अज्ञात माना जाता है, इसलिए शाखा status पर नहीं, canSend पर बनाएँ, जिसे domain.dig(:sending, :canSend) के रूप में पढ़ा जाता है।
list वर्णानुक्रम में डोमेन का एक OpenEmail::Page लौटाता है, और list_all उन सबको एक Array में लौटाता है। iterate उन्हें एक-एक करके block में yield करता है। block के बिना यह एक Enumerator लौटाता है।
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)update डोमेन का कस्टम ट्रैकिंग डोमेन सेट करता है, फिर से जाँचता है या हटाता है, links.acme.com जैसा एक subdomain, और get वाला ही Hash लौटाता है। tracking हर read पर इसे बताता है। जब तक कोई जाँच पास न हो, tracking.status pending रहता है और ट्रैक किए गए लिंक तथा open pixel डिफ़ॉल्ट OpenEmail होस्ट ही इस्तेमाल करते रहते हैं। जाँच पास होने पर यह active हो जाता है और डोमेन का नया मेल दोनों के लिए ट्रैकिंग डोमेन इस्तेमाल करता है।
get डोमेन पर मौजूद पते भी सूचीबद्ध करता है। addresses.list संबंधित कॉल है: वे पते जिन्हें यह कुंजी From हेडर में डाल सकती है, जो इससे संकरा है, हर एक canSend फ़ैसले के साथ। यह एक OpenEmail::AddressBookPage लौटाता है, जो उन्हें items के बजाय addresses में रखता है, domains और unrestricted के साथ। इसका list_all एक OpenEmail::AddressBook लौटाता है।
app_host अपना अलग namespace है, client.app_host। get, set, verify और delete वर्कस्पेस का वेब ऐप पता पढ़ते और बदलते हैं, इनमें से किसी डोमेन पर या वर्कस्पेस के नियंत्रण वाले किसी दूसरे डोमेन पर mailbox.acme.com जैसा एक subdomain, जहाँ उसके लोग वर्कस्पेस के ब्रांड के तहत साइन इन करते हैं। set प्रकाशित करने वाले DNS रिकॉर्ड लौटाता है, record में और, वर्कस्पेस के बाहर के डोमेन पर, ownershipRecord में। delete, और कोई पता बदलने वाला set, OAuth ऐप से सत्यापन कोड माँगते हैं: जब तक उसके पास कोड न हो, कॉल एक 403 raise करती है जिसका step_up_required? true होता है।
branding वह ब्रांड सेट करता है। get मार्क, लोगो, dark mode के लोगो और साइन-इन फ़ोटो के लिंक, दोनों फ़ॉन्ट और साइन-इन बैकग्राउंड पढ़ता है। update फ़ॉन्ट और बैकग्राउंड बदलता है, upload_image(variant, data, content_type: nil) चारों में से एक चित्र अपलोड करता है, और remove_image(variant) एक हटाता है। variant mark, wordmark, wordmark-dark या login-background है, और OpenEmail::BRAND_IMAGE_VARIANTS उनके नाम बताता है। data binary String, IO या Pathname है। Pathname("logo.svg") जैसा Pathname, File या Rails अपलोड अपना टाइप साथ लाता है। दूसरे बाइट्स को content_type: चाहिए, और बिना टाइप वाला चित्र 422 invalid_image के साथ अस्वीकार होता है। लोगो ही वेब ऐप पते को, और paid प्लान पर वर्कस्पेस की ओर से भेजे गए ईमेल को, ब्रांड करता है।
पैरामीटर: domains.get
idStringआवश्यक- `domains.list` से मिली id, डोमेन जोड़ते समय बना एक UUID, hostname नहीं, इसलिए `get("example.com")` कुछ नहीं ढूँढता। खोज id के साथ-साथ कुंजी के अपने वर्कस्पेस तक सीमित है, इसलिए दूसरे वर्कस्पेस का डोमेन 403 के बजाय 404 है, जो `OpenEmail::NotFoundError` के रूप में raise होता है। nil या ख़ाली id कुछ भी भेजे जाने से पहले ArgumentError raise करती है।
पैरामीटर: domains.update
idStringआवश्यक- वही domain id जो `get` लेता है। इसके लिए ज़रूरी scope `domains:write` है।
trackingHostString or nil- डोमेन का एक subdomain, अधिकतम 512 वर्ण, जैसे `links.acme.com`। इसे trim करके छोटे अक्षरों में बदला जाता है, और आगे का `https://` या `http://`, कोई path और आख़िरी बिंदु हटा दिया जाता है। नया मान उसी कॉल में सत्यापित, सहेजा और जाँचा जाता है। डोमेन के पास पहले से मौजूद मान जाँच फिर से चलाता है, जब तक पिछली जाँच 30 सेकंड से कम पहले न हुई हो। ट्रैकिंग डोमेन हटाने के लिए nil या ख़ाली String पास करें, और उसे न छेड़ने के लिए फ़ील्ड को छोड़ दें।
अस्वीकृत होस्ट एक OpenEmail::ApiError raise करता है जो param में trackingHost का नाम लेता है: ऐसे नाम के लिए 422 invalid_tracking_host जो इस्तेमाल नहीं हो सकता, जैसे डोमेन के बाहर का, नए होस्ट के लिए 409 domain_not_verified जब receiving.verified false हो और डोमेन का _openemail-challenge TXT रिकॉर्ड अभी प्रकाशित न हुआ हो, और 409 tracking_host_in_use ऐसे नाम के लिए जिसे कोई दूसरा डोमेन पहले से इस्तेमाल कर रहा हो, या जब ट्रैकिंग डोमेन किसी दूसरे OpenEmail सर्वर द्वारा प्रबंधित हो। 422 OpenEmail::ValidationError के रूप में आता है और हर 409 OpenEmail::ConflictError के रूप में। ख़ास पतों तक सीमित कुंजी को 422 capability_unsupported मिलता है, क्योंकि ट्रैकिंग डोमेन डोमेन के हर पते पर लागू होता है।
patch keyword arguments या एक Hash है, और इसके फ़ील्ड API के camelCase नाम बनाए रखते हैं, इसलिए tracking_host: जैसा लिखा है वैसा भेजा जाता है और 422 unknown_parameter के साथ अस्वीकार होता है। update catchAll, files.acme.com जैसे files डोमेन के लिए storageHost, और dmarcPolicy भी लेता है। हर फ़ील्ड वैकल्पिक है और मेथड संदर्भ हर एक को कवर करता है। gem update पर read की तरह पुनः प्रयास करता है, क्योंकि दोहराने पर होस्ट पहले से सेट मिलता है और ज़्यादा से ज़्यादा उसे फिर जाँचा जाता है।
जवाब: एक डोमेन (domains.get)
objectString- हमेशा स्ट्रिंग `domain`, `list` की पंक्तियों पर भी और इस पर भी।
idString- डोमेन का UUID। पंक्ति के पूरे जीवनकाल में स्थिर, और इकलौता हैंडल जिसे डोमेन की दूसरी कॉल स्वीकार करती हैं।
domainString- सादा होस्टनाम, छोटे अक्षरों में: `example.com`। पूरे उत्पाद में अद्वितीय, हर domain का एक ही मालिक, इसलिए दो workspaces एक ही domain पर दावा नहीं कर सकते।
receiving.verifiedBoolean- तब true जब DNS ने दिखा दिया कि domain का MX ऐसे होस्ट का नाम ले रहा है जो उसकी मेल यहाँ लाता है, और जहाँ पंक्ति में चुनौती टोकन है वहाँ उससे मेल खाता `_openemail-challenge` TXT रिकॉर्ड भी मिल गया। अकेला MX कुछ भी साबित नहीं करता, क्योंकि जिन सब domains के लिए हम मेल लेते हैं वे सभी वही होस्टनाम प्रकाशित करते हैं। इसीलिए टोकन है, और इसीलिए यही ध्वज वह द्वार है जिसे inbound डिलीवरी मेल स्वीकार करने से पहले जाँचती है।
receiving.verifiedAtString or nil- सत्यापन कब पास हुआ, ISO 8601 String के रूप में। जब तक पास न हुआ हो तब तक nil, और `verified` ठीक इसी कॉलम से निकाला जाता है, इसलिए दोनों में कभी असहमति नहीं हो सकती।
receiving.catchAllBoolean- क्या कोई भी local-part स्वीकार होता है। यह नियम बनने के बाद जोड़े गए डोमेन के लिए डिफ़ॉल्ट रूप से चालू है। इसके बंद रहने पर सिर्फ़ डोमेन पर नामित पते स्वीकार होते हैं और बाक़ी SMTP के समय अस्वीकार होते हैं, इसलिए प्रेषक को चुप्पी के बजाय bounce मिलता है।
receiving.lastCheckedAtString or nil- इस डोमेन के बारे में DNS से आख़िरी बार कब पूछा गया। जब DNS से कभी नहीं पूछा गया तो nil, जो एक मिनट पहले डोमेन जोड़ने वाले व्यक्ति के लिए विफलता से बहुत अलग पढ़ा जाता है। असत्यापित डोमेन पढ़ने पर, आख़िरी जाँच 20 सेकंड से पुरानी हो जाने पर, DNS से फिर पूछा जाता है, इसलिए `get` को बार-बार कॉल करना सत्यापन का इंतज़ार करने का एक तरीका है, और `verify` तुरंत जाँचता है।
receiving.errorString or nil- आख़िरी जाँच पास क्यों नहीं हुई, ऐसे शब्दों में जिन पर मालिक कार्रवाई कर सके: `No MX records yet. DNS changes can take a few minutes to spread.` एक आम उदाहरण है। जाँच पास होते ही यह nil हो जाता है, और यह निकाला नहीं, सहेजा जाता है, इसलिए reload और शेड्यूल की गई दोबारा जाँच एक ही बात कहते हैं।
sending.statusString- बाहर जाने वाली signing की स्थिति जैसी आख़िरी जाँच ने देखी: `verified`, `pending`, `failed`, `no_identity` या `unknown`। यह सहेजी गई जाँच से पढ़ी जाती है, इसलिए `sending.checkedAt` बताता है कि यह कितनी पुरानी है।
sending.canSendBoolean- इस domain से भेजना अभी स्वीकार होगा या नहीं। एक दिन से पुराना नकारात्मक निर्णय इनकार नहीं, अज्ञात माना जाता है, इसलिए यह true हो सकता है जबकि `status` `pending` हो। भेजने से पहले इसी पर शाखा बनाएँ: इसका false होना यानी इस domain से `emails.send` 409 `domain_not_sendable` के साथ अस्वीकार होगा।
sending.checkedAtString or nil- signing की स्थिति आख़िरी बार कब जाँची गई, ISO 8601 String के रूप में। जब कभी नहीं जाँची गई तो nil, जो विफलता से बहुत अलग पढ़ा जाता है।
sending.errorString or nil- आख़िरी signing विफलता शब्दों में, या पास होते ही nil।
sending.noteString- पाँच वाक्यों में से एक, जो `sending.status` के आधार पर चुना जाता है और बताता है कि उस स्थिति का मतलब क्या है, ऐसे शब्दों में जिन पर डोमेन का मालिक कार्रवाई कर सके। यह इंसान के पढ़ने के लिए गद्य है, इसलिए शाखा इस पर नहीं, `sending.canSend` पर बनाएँ।
trackingHash- domain का custom tracking domain, `list` की पंक्तियों पर भी और इस पर भी, और यही वह चीज़ है जिसे `update` बदलता है।
tracking.hostString or nil- ट्रैकिंग डोमेन, जैसे `links.acme.com`, या कोई सेट न हो तो nil।
tracking.statusString- `none` का अर्थ है कोई tracking domain सेट नहीं है, `pending` का अर्थ है वह कभी कोई जाँच पास नहीं कर सका, `active` का अर्थ है नई मेल उसका उपयोग करती है, और `failed` का अर्थ है वह पहले पास हुआ था और तब से उपयोग से बाहर हो गया। कोई सक्रिय होस्ट लगातार तीन जाँच विफल होने पर, या उसकी आख़िरी पास हुई जाँच के 2 घंटे से ज़्यादा पुराना हो जाने पर उपयोग से बाहर हो जाता है।
tracking.activeBoolean- ठीक तभी true, जब `status` `active` हो, यानी जब डोमेन से भेजे गए नए मेल के tracked लिंक और open पिक्सेल इस होस्ट का उपयोग करते हैं।
tracking.targetString- वह पता जिसकी ओर CNAME रिकॉर्ड इशारा करता है, सिर्फ़ इसी ट्रैकिंग डोमेन के लिए तैयार किया गया। जब तक `host` nil है, और जब तक नए होस्ट का पता अभी तैयार हो रहा है, यह ख़ाली String है।
tracking.recordHash or nil- प्रकाशित करने वाला रिकॉर्ड, `type` (हमेशा `CNAME`), `name` और `value` वाला Hash, `host` के नाम पर और `target` उसका मान। जब कोई ट्रैकिंग डोमेन न हो, और जब तक नए होस्ट का पता अभी तैयार हो रहा है, यह nil है, इसलिए `dig(:tracking, :record, :value)` इसे सुरक्षित रूप से पढ़ता है।
tracking.checkedAtString or nil- होस्ट आख़िरी बार कब जाँचा गया, ISO 8601 String के रूप में। पहली जाँच तक nil।
tracking.verifiedAtString or nil- आख़िरी बार कोई जाँच कब पास हुई, ISO 8601 String के रूप में। जो होस्ट कभी कोई जाँच पास नहीं कर पाया उसके लिए nil।
tracking.errorString or nil- आख़िरी जाँच में क्या मिला, ऐसे शब्दों में जिन पर डोमेन का मालिक कार्रवाई कर सके। जब आख़िरी जाँच पास हुई हो या अभी कोई जाँच न चली हो तो nil। जो होस्ट एक या दो जाँच में विफल हुआ है वह अब भी `active` है और कारण यहाँ रखता है।
addressesArray<Hash>- डोमेन की हर पता पंक्ति, जो `get` `list` पंक्ति के ऊपर जोड़ता है। इसमें वे पंक्तियाँ भी शामिल हैं जो डिलीवरी ने catch-all के तहत ख़ुद लिखीं, और catch-all बंद होते ही उनका स्वीकार होना बंद हो जाता है, इसलिए यह Array उन पतों की सूची नहीं है जो मेल पाएँगे।
addresses[].addressString- पूरा पता, संग्रहित local-part और होस्टनाम से दोबारा बनाया गया और छोटे अक्षरों में, ताकि वह ऊपर के `domain` से भटकने के बजाय हमेशा उससे मेल खाए।
addresses[].enabledBoolean- false पते को निष्क्रिय करता है, और निष्क्रिय पता catch-all चालू होने पर भी अस्वीकार होता है। हर पंक्ति किसी भी हाल में सूचीबद्ध होती है, इसलिए Array को काम करने वाले पतों का सेट मानने के बजाय इस पर फ़िल्टर करें।
createdAtString- डोमेन पंक्ति कब जोड़ी गई, ISO 8601 String के रूप में। यह डोमेन के सत्यापित होने का समय नहीं है: वह `receiving.verifiedAt` है, जो इसके सेट रहते हुए भी nil हो सकता है।