डोमेन
`domains->list`, `listAll`, `iterate`, `get` और `update`।
हर मेथड
$page = $client->domains->list(); foreach ($page as $row) { echo $row['domain'], ' ', $row['sending']['canSend'] ? 'can send' : 'cannot send yet', PHP_EOL;} $domain = $client->domains->get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f');echo $domain['receiving']['verified'] ? 'receiving' : 'not verified yet', ' ', $domain['sending']['status'], PHP_EOL; foreach ($domain['addresses'] as $entry) { echo $entry['address'], ' ', $entry['enabled'] ? 'on' : 'off', PHP_EOL;}प्राप्त करना और भेजना दो स्वतंत्र तथ्य हैं और दो arrays के रूप में लौटाए जाते हैं। receiving.verified का मतलब है कि डोमेन का MX उसकी मेल यहाँ लाता है और उसकी ownership challenge प्रकाशित है। sending बाहर जाने वाली signing जाँच बताता है: status verified, pending, failed, no_identity या unknown होता है, और canSend बताता है कि डोमेन से send अभी स्वीकार होगा या नहीं। एक दिन से पुराना नकारात्मक फ़ैसला अस्वीकार के बजाय अज्ञात माना जाता है, इसलिए status के बजाय canSend पर branch करें, जिसे $domain['sending']['canSend'] के रूप में पढ़ा जाता है।
list वर्णानुक्रम में डोमेन का एक OpenEmail\Result\Page लौटाता है, और listAll उन सबको एक array में लौटाता है। iterate एक Generator लौटाता है जो उन्हें एक-एक करके yield करता है।
$domainId = 'b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f'; $updated = $client->domains->update($domainId, ['trackingHost' => 'links.acme.com']);$record = $updated['tracking']['record'];echo $updated['tracking']['status'], ' ', $record['name'] ?? '', ' ', $record['value'] ?? '', PHP_EOL; $client->domains->update($domainId, ['trackingHost' => null]);update डोमेन का custom tracking डोमेन सेट करता है, फिर से जाँचता है या हटाता है, जो links.acme.com जैसा subdomain होता है, और get जैसा ही array लौटाता है। tracking हर read पर इसे बताता है। जब तक कोई जाँच पास न हो, tracking.status pending रहता है और tracked links और open pixel डिफ़ॉल्ट OpenEmail होस्ट का इस्तेमाल करते रहते हैं। जाँच पास होने पर यह active हो जाता है और डोमेन से आने वाली नई मेल दोनों के लिए tracking डोमेन का इस्तेमाल करती है।
get डोमेन पर मौजूद पते भी सूचीबद्ध करता है। addresses->list संबंधित कॉल है: वे पते जिन्हें यह कुंजी From हेडर में डाल सकती है, जो इससे संकरा है, हर एक canSend फ़ैसले के साथ। यह एक OpenEmail\Result\AddressBookPage लौटाता है, जो उन्हें items के बजाय addresses में रखता है, domains और unrestricted के साथ। इसका listAll एक OpenEmail\Result\AddressBook लौटाता है।
appHost अपना अलग नेमस्पेस है, $client->appHost। get, set, verify और delete वर्कस्पेस के वेब ऐप का पता पढ़ते और बदलते हैं, जो इनमें से किसी डोमेन या वर्कस्पेस द्वारा नियंत्रित किसी दूसरे डोमेन पर mailbox.acme.com जैसा subdomain होता है, जहाँ इसके लोग वर्कस्पेस के brand के तहत साइन इन करते हैं। set प्रकाशित करने के लिए DNS records लौटाता है, record में और, वर्कस्पेस के बाहर के डोमेन पर, ownershipRecord में। delete, और पते को बदलने वाला set, OAuth ऐप से सत्यापन कोड माँगते हैं: जब तक उसके पास कोड न हो, कॉल ऐसा 403 throw करती है जिसका isStepUpRequired() true होता है।
branding वह brand सेट करता है। branding->get mark, logo, dark mode वाले logo और sign-in photo के links, दो fonts और sign-in background पढ़ता है। branding->update fonts और background बदलता है, branding->uploadImage($variant, $data, contentType: ...) चार images में से एक अपलोड करता है, और branding->removeImage($variant) एक को हटाता है। variant mark, wordmark, wordmark-dark या login-background होता है, और OpenEmail\Constants\BrandImageVariants इनके नाम देता है। data बाइट्स की स्ट्रिंग, stream resource, SplFileInfo या PSR-7 stream या अपलोड की गई फ़ाइल होता है। new \SplFileInfo('logo.svg') जैसा SplFileInfo, किसी फ़ाइल पर खोला गया stream, या Laravel या Symfony का upload अपना टाइप साथ लाता है। बाकी बाइट्स को contentType: चाहिए, और बिना टाइप वाली image 422 invalid_image के साथ अस्वीकार होती है। logo ही वह चीज़ है जो वेब ऐप के पते पर, और paid plan पर वर्कस्पेस के लिए भेजी गई ईमेल पर, brand लगाती है।
पैरामीटर: domains->get
idstringआवश्यक- `domains->list` से मिली id, डोमेन जोड़ते समय बनाई गई एक UUID, hostname नहीं, इसलिए `get('example.com')` कुछ नहीं ढूँढता। खोज id के साथ-साथ कुंजी के अपने वर्कस्पेस तक सीमित है, इसलिए किसी दूसरे वर्कस्पेस का डोमेन 403 के बजाय 404 है, जो `NotFoundException` के रूप में throw होता है। ख़ाली id कुछ भी भेजे जाने से पहले `InvalidArgumentException` throw करती है।
पैरामीटर: domains->update
idstringआवश्यक- वही domain id जो `get` लेता है। इसके लिए ज़रूरी scope `domains:write` है।
trackingHoststring or null- डोमेन का एक subdomain, अधिकतम 512 अक्षर, जैसे `links.acme.com`। इसे trim और lowercase किया जाता है, और शुरुआत का `https://` या `http://`, कोई path और अंत का बिंदु हटा दिया जाता है। नया मान उसी कॉल में validate, सहेजा और जाँचा जाता है। डोमेन के पास पहले से मौजूद मान पर जाँच फिर से चलती है, जब तक पिछली जाँच 30 सेकंड से कम पहले न हुई हो। tracking डोमेन हटाने के लिए null या ख़ाली स्ट्रिंग पास करें, और उसे जस का तस छोड़ने के लिए कुंजी छोड़ दें।
अस्वीकार किया गया होस्ट एक ApiException throw करता है जो param में trackingHost का नाम लेता है: ऐसे नाम के लिए 422 invalid_tracking_host जिसका इस्तेमाल नहीं हो सकता, जैसे डोमेन के बाहर का नाम, नए होस्ट के लिए 409 domain_not_verified जब receiving.verified false हो और डोमेन का _openemail-challenge TXT record अभी प्रकाशित न हुआ हो, और ऐसे नाम के लिए 409 tracking_host_in_use जिसे कोई दूसरा डोमेन पहले से इस्तेमाल करता है, या जब tracking डोमेन किसी दूसरे OpenEmail सर्वर द्वारा प्रबंधित हो। 422 ValidationException के रूप में और हर 409 ConflictException के रूप में आता है। ख़ास पतों तक सीमित कुंजी को 422 capability_unsupported मिलता है, क्योंकि tracking डोमेन डोमेन के हर पते पर लागू होता है।
patch API के camelCase नामों वाली कुंजियों का एक array है, इसलिए tracking_host जैसी कुंजी लिखे अनुसार भेजी जाती है और 422 unknown_parameter के साथ अस्वीकार होती है। update catchAll, files.acme.com जैसे files डोमेन के लिए storageHost, और dmarcPolicy भी लेता है। हर कुंजी वैकल्पिक है और मेथड संदर्भ हर एक को समझाता है। क्लाइंट update को read की तरह retry करता है, क्योंकि दोहराने पर होस्ट पहले से सेट मिलता है और ज़्यादा से ज़्यादा उसे फिर से जाँचा जाता है।
जवाब: एक डोमेन (domains->get)
objectstring- हमेशा स्ट्रिंग `domain`, `list` की पंक्तियों पर भी और इस पर भी।
idstring- डोमेन का UUID। पंक्ति के पूरे जीवनकाल में स्थिर, और इकलौता हैंडल जिसे डोमेन की दूसरी कॉल स्वीकार करती हैं।
domainstring- सादा होस्टनाम, छोटे अक्षरों में: `example.com`। पूरे उत्पाद में अद्वितीय, हर domain का एक ही मालिक, इसलिए दो workspaces एक ही domain पर दावा नहीं कर सकते।
receiving.verifiedbool- तब true जब DNS ने दिखा दिया कि domain का MX ऐसे होस्ट का नाम ले रहा है जो उसकी मेल यहाँ लाता है, और जहाँ पंक्ति में चुनौती टोकन है वहाँ उससे मेल खाता `_openemail-challenge` TXT रिकॉर्ड भी मिल गया। अकेला MX कुछ भी साबित नहीं करता, क्योंकि जिन सब domains के लिए हम मेल लेते हैं वे सभी वही होस्टनाम प्रकाशित करते हैं। इसीलिए टोकन है, और इसीलिए यही ध्वज वह द्वार है जिसे inbound डिलीवरी मेल स्वीकार करने से पहले जाँचती है।
receiving.verifiedAtstring or null- सत्यापन कब पास हुआ, ISO 8601 स्ट्रिंग के रूप में। जब तक पास न हुआ हो तब तक यह null है, और `verified` ठीक इसी column से निकाला जाता है, इसलिए दोनों कभी असहमत नहीं हो सकते।
receiving.catchAllbool- क्या कोई भी local-part स्वीकार होता है। यह नियम बनने के बाद जोड़े गए डोमेन के लिए डिफ़ॉल्ट रूप से चालू है। इसके बंद रहने पर सिर्फ़ डोमेन पर नामित पते स्वीकार होते हैं और बाक़ी SMTP के समय अस्वीकार होते हैं, इसलिए प्रेषक को चुप्पी के बजाय bounce मिलता है।
receiving.lastCheckedAtstring or null- इस डोमेन के बारे में DNS से आख़िरी बार कब पूछा गया। जब DNS से कभी पूछा ही नहीं गया तो यह null है, जो एक मिनट पहले डोमेन जोड़ने वाले व्यक्ति को विफलता से बिल्कुल अलग पढ़ा जाता है। असत्यापित डोमेन को पढ़ने पर, पिछली जाँच 20 सेकंड से पुरानी होने पर DNS से फिर पूछा जाता है, इसलिए `get` को poll करना सत्यापन का इंतज़ार करने का एक तरीक़ा है, और `verify` तुरंत जाँचता है।
receiving.errorstring or null- पिछली जाँच क्यों पास नहीं हुई, ऐसे शब्दों में जिन पर मालिक कार्रवाई कर सके: `No MX records yet. DNS changes can take a few minutes to spread.` एक सामान्य उदाहरण है। जाँच पास होते ही यह null हो जाता है, और यह निकाला नहीं बल्कि सहेजा जाता है, इसलिए reload और शेड्यूल की गई दोबारा जाँच एक ही बात कहते हैं।
sending.statusstring- बाहर जाने वाली signing की स्थिति जैसी आख़िरी जाँच ने देखी: `verified`, `pending`, `failed`, `no_identity` या `unknown`। यह सहेजी गई जाँच से पढ़ी जाती है, इसलिए `sending.checkedAt` बताता है कि यह कितनी पुरानी है।
sending.canSendbool- इस domain से भेजना अभी स्वीकार होगा या नहीं। एक दिन से पुराना नकारात्मक निर्णय इनकार नहीं, अज्ञात माना जाता है, इसलिए यह true हो सकता है जबकि `status` `pending` हो। भेजने से पहले इसी पर शाखा बनाएँ: इसका false होना यानी इस domain से `emails->send` 409 `domain_not_sendable` के साथ अस्वीकार होगा।
sending.checkedAtstring or null- signing स्थिति आख़िरी बार कब जाँची गई, ISO 8601 स्ट्रिंग के रूप में। जब कभी जाँची ही नहीं गई तो यह null है, जो विफलता से बिल्कुल अलग पढ़ा जाता है।
sending.errorstring or null- आख़िरी signing विफलता शब्दों में, या पास हो जाने पर null।
sending.notestring- पाँच वाक्यों में से एक, जो `sending.status` के आधार पर चुना जाता है और बताता है कि उस स्थिति का मतलब क्या है, ऐसे शब्दों में जिन पर डोमेन का मालिक कार्रवाई कर सके। यह इंसान के पढ़ने के लिए गद्य है, इसलिए शाखा इस पर नहीं, `sending.canSend` पर बनाएँ।
trackingarray- domain का custom tracking domain, `list` की पंक्तियों पर भी और इस पर भी, और यही वह चीज़ है जिसे `update` बदलता है।
tracking.hoststring or null- tracking domain, जैसे `links.acme.com`, या कोई सेट न होने पर null।
tracking.statusstring- `none` का अर्थ है कोई tracking domain सेट नहीं है, `pending` का अर्थ है वह कभी कोई जाँच पास नहीं कर सका, `active` का अर्थ है नई मेल उसका उपयोग करती है, और `failed` का अर्थ है वह पहले पास हुआ था और तब से उपयोग से बाहर हो गया। कोई सक्रिय होस्ट लगातार तीन जाँच विफल होने पर, या उसकी आख़िरी पास हुई जाँच के 2 घंटे से ज़्यादा पुराना हो जाने पर उपयोग से बाहर हो जाता है।
tracking.activebool- ठीक तभी true, जब `status` `active` हो, यानी जब डोमेन से भेजे गए नए मेल के tracked लिंक और open पिक्सेल इस होस्ट का उपयोग करते हैं।
tracking.targetstring- वह पता जिस पर CNAME रिकॉर्ड इंगित करता है, केवल इसी tracking डोमेन के लिए तैयार किया गया। जब तक `host` null है, और जब तक नए होस्ट का पता तैयार हो रहा है, यह खाली स्ट्रिंग रहता है।
tracking.recordarray or null- प्रकाशित करने वाला record, `type` (हमेशा `CNAME`), `name` और `value` वाला array, जिसका नाम `host` पर और मान `target` पर है। जब कोई tracking डोमेन न हो, और जब तक नए होस्ट का पता तैयार हो रहा हो, यह null है, इसलिए `$domain['tracking']['record']['value'] ?? null` इसे सुरक्षित रूप से पढ़ता है।
tracking.checkedAtstring or null- होस्ट आख़िरी बार कब जाँचा गया, ISO 8601 स्ट्रिंग के रूप में। पहली जाँच तक यह null है।
tracking.verifiedAtstring or null- कोई जाँच आख़िरी बार कब पास हुई, ISO 8601 स्ट्रिंग के रूप में। जिस होस्ट ने कभी जाँच पास नहीं की उसके लिए यह null है।
tracking.errorstring or null- पिछली जाँच में क्या मिला, ऐसे शब्दों में जिन पर डोमेन का मालिक कार्रवाई कर सके। जब पिछली जाँच पास हुई हो या अभी तक कोई नहीं चली हो तो यह null है। एक या दो जाँच में विफल हुआ होस्ट अब भी `active` रहता है और कारण यहाँ रखता है।
addressesarray- डोमेन की हर पते की पंक्ति, जो `get` किसी `list` पंक्ति के ऊपर जोड़ता है। इसमें वे पंक्तियाँ भी हैं जो delivery ने catch-all के तहत ख़ुद लिखीं, और catch-all बंद होते ही उन्हें स्वीकार करना बंद हो जाता है, इसलिए यह सूची उन पतों की सूची नहीं है जो मेल पाएँगे।
addresses[].addressstring- पूरा पता, संग्रहित local-part और होस्टनाम से दोबारा बनाया गया और छोटे अक्षरों में, ताकि वह ऊपर के `domain` से भटकने के बजाय हमेशा उससे मेल खाए।
addresses[].enabledbool- false पते को अक्षम करता है, और अक्षम पता catch-all चालू होने पर भी अस्वीकार होता है। हर पंक्ति दोनों ही स्थितियों में सूची में रहती है, इसलिए सूची को काम करने वाले पतों का समूह मानने के बजाय इस पर फ़िल्टर करें।
createdAtstring- डोमेन की पंक्ति कब जोड़ी गई, ISO 8601 स्ट्रिंग के रूप में। यह वह समय नहीं है जब डोमेन सत्यापित हुआ: वह `receiving.verifiedAt` है, जो इसके सेट होने पर भी null हो सकता है।