डोमेन अपडेट करें
डोमेन का कस्टम tracking डोमेन और कस्टम files डोमेन सेट करता है, दोबारा जाँचता है या हटाता है — डोमेन के बारे में यही दो चीज़ें यह API बदल सकता है।
असली कॉल आपकी अपनी कुंजी से आपके वर्कस्पेस पर चलाता है।
PATCH /domains/{id}
डोमेन का कस्टम tracking डोमेन और कस्टम files डोमेन सेट करता है, दोबारा जाँचता है या हटाता है — डोमेन के बारे में यही दो चीज़ें यह API बदल सकता है।
अनुरोध
एक डोमेन के पास एक कस्टम tracking डोमेन और एक कस्टम files डोमेन हो सकता है, दोनों उसी के चुने हुए सबडोमेन, जैसे links.acme.com और files.acme.com, जैसे ही वह सत्यापित हो जाए या उसका _openemail-challenge TXT रिकॉर्ड प्रकाशित हो। उसका मेल प्राप्त करना शुरू करना ज़रूरी नहीं। इनमें से कोई सेट करने पर केवल उसी नाम के लिए एक पता तैयार किया जाता है, जो target में बताया जाता है, और record वह CNAME रिकॉर्ड है जो उस नाम को उस पर इंगित करता है। जाँच पास होने के बाद, डोमेन से भेजे गए नए मेल में tracked लिंक और open पिक्सेल डिफ़ॉल्ट होस्ट के बजाय https://links.acme.com/t/... का उपयोग करते हैं, और उससे भेजी गई फ़ाइलों के डाउनलोड लिंक https://files.acme.com/f/... का।
पैरामीटर
trackingHoststring | null- tracked लिंक और open पिक्सेल के लिए इस्तेमाल होने वाला सबडोमेन, अधिकतम 512 अक्षर। इसे ट्रिम और lowercase किया जाता है, और जाँच से पहले शुरू का `https://` या `http://`, कोई पथ और अंत का बिंदु हटा दिया जाता है। नया मान मौजूदा tracking डोमेन की जगह ले लेता है, मौजूदा मान भेजने पर जाँच दोबारा चलती है, `null` या खाली स्ट्रिंग उसे हटा देती है, और फ़ील्ड छोड़ देने पर वह वैसा ही रहता है।
storageHoststring | null- फ़ाइल डाउनलोड लिंक के लिए इस्तेमाल होने वाला सबडोमेन, उसी तरह साफ़ किया गया और उन्हीं 512 अक्षरों तक सीमित। नया मान मौजूदा files डोमेन की जगह ले लेता है, मौजूदा मान भेजने पर जाँच दोबारा चलती है, `null` या खाली स्ट्रिंग उसे हटा देती है, और फ़ील्ड छोड़ देने पर वह वैसा ही रहता है।
बॉडी कुंजियों के बारे में सख़्त है और इस बारे में ढीली कि आप कितनी भेजते हैं। trackingHost और storageHost के अलावा कोई भी कुंजी 422 unknown_parameter है, और जिस बॉडी में इनमें से कोई नहीं है वह एक no-op है जो डोमेन को उसकी मौजूदा स्थिति के साथ 200 में लौटा देती है। दोनों एक ही कॉल में जा सकते हैं, और वे क्रम से लागू होते हैं, पहले trackingHost: अस्वीकृत trackingHost कॉल को वहीं रोक देता है, storageHost छुआ भी नहीं जाता, और अस्वीकृत storageHost पहले हो चुके trackingHost परिवर्तन को यथावत छोड़ देता है। जब किसी एक को अपने दम पर टिकना हो, तो उन्हें अलग-अलग भेजें।
tracking डोमेन और files डोमेन सेट करें
domains:write चाहिए। हर होस्ट उसी कॉल में सत्यापित, सहेजा और जाँचा जाता है, इसलिए प्रतिक्रिया में उस पहली जाँच का परिणाम पहले से होता है। यह वही बॉडी है जो GET /domains/{id} देता है।
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "trackingHost": "links.acme.com", "storageHost": "files.acme.com" }'{ "object": "domain", "id": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "receiving": { "verified": true, "verifiedAt": "2026-08-14T10:02:00.000Z", "catchAll": false, "lastCheckedAt": "2026-08-29T06:00:00.000Z", "error": null }, "sending": { "status": "verified", "canSend": true, "checkedAt": "2026-08-29T06:00:00.000Z", "error": null, "note": "Mail from this domain is signed and can be sent." }, "tracking": { "host": "links.acme.com", "status": "pending", "active": false, "target": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk", "record": { "type": "CNAME", "name": "links.acme.com", "value": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk" }, "checkedAt": "2026-08-29T06:05:12.000Z", "verifiedAt": null, "error": "links.acme.com does not resolve yet. Add a CNAME record named links.acme.com with the value oelinks3f9a1c7e2b8d4a60.edge.openemail.uk, then check again." }, "storage": { "host": "files.acme.com", "status": "pending", "active": false, "target": "oefiles81c40d6b2f7e9a35.edge.openemail.uk", "record": { "type": "CNAME", "name": "files.acme.com", "value": "oefiles81c40d6b2f7e9a35.edge.openemail.uk" }, "checkedAt": "2026-08-29T06:05:12.000Z", "verifiedAt": null, "error": "files.acme.com does not resolve yet. Add a CNAME record named files.acme.com with the value oefiles81c40d6b2f7e9a35.edge.openemail.uk, then check again." }, "addresses": [ { "address": "[email protected]", "enabled": true } ], "createdAt": "2026-08-14T09:55:11.000Z"}tracking.record और storage.record को अपने DNS प्रदाता पर सादे CNAME के रूप में प्रकाशित करें, किसी भी proxying को बंद रखकर। जाँच हर नाम को resolve करती है, फिर https://links.acme.com/t/v/<nonce> या https://files.acme.com/f/v/<nonce> से ऐसा उत्तर माँगती है जिस पर OpenEmail का हस्ताक्षर हो। redirect जाँच विफल कर देता है, और नाम के आगे लगा कोई proxy भी।
रिकॉर्ड resolve होने के बाद जाँच बता सकती है कि नाम OpenEmail की ओर इंगित करता है और चालू किए जाने की प्रतीक्षा में है। यह उसका HTTPS प्रमाणपत्र जारी होना है, जो हमारी ओर होता है, आपसे कुछ नहीं माँगता और थोड़ा समय ले सकता है। पूरा होते ही, पास होने वाली अगली जाँच status को active कर देती है।
अगर कॉल के दौरान पता तैयार नहीं किया जा सका, तो record null होता है, target खाली स्ट्रिंग होता है और error बताता है कि उसे तैयार किया जा रहा है। यह बिना किसी और कॉल के कुछ ही मिनटों में पूरा हो जाता है, इसलिए रिकॉर्ड पाने के लिए GET /domains/{id} से डोमेन दोबारा पढ़ें।
दोनों नाम स्वतंत्र हैं। केवल एक फ़ील्ड लेकर आई कॉल दूसरे ऑब्जेक्ट को बिल्कुल वैसा ही छोड़ देती है, इसलिए बाद में files सेट करना पहले से चालू tracking डोमेन को कभी परेशान नहीं करता।
दोबारा जाँचें, या हटाएँ
अगली निर्धारित जाँच की प्रतीक्षा करने के बजाय अभी जाँच चलाने के लिए वही होस्ट भेजें जो डोमेन के पास पहले से है। अगर पिछली जाँच, निर्धारित हो या नहीं, 30 सेकंड से कम पहले चली थी, तो कॉल संग्रहीत स्थिति ज्यों की त्यों लौटा देती है। किसी नाम को हटाने के लिए उस फ़ील्ड में null भेजें, और दूसरे फ़ील्ड को छोड़ दें ताकि उसका नाम बना रहे।
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "trackingHost": null }'{ "host": null, "status": "none", "active": false, "target": "", "record": null, "checkedAt": null, "verifiedAt": null, "error": null}पहले भेजे जा चुके मेल के लिंक उसी होस्ट के साथ रहते हैं जिसके साथ वे गए थे, और यह बात tracked लिंक की तरह किसी फ़ाइल के डाउनलोड लिंक पर भी लागू होती है। कोई नाम हटाने या बदलने के बाद, जब तक पुराना CNAME रिकॉर्ड बना रहता है, वे लिंक काम करते रहते हैं। किसी नाम को दोबारा सेट करने पर उसे अलग record मिल सकता है, इसलिए वही प्रकाशित करें जो प्रतिक्रिया बताती है।
tracking ऑब्जेक्ट
hoststring | null- tracking डोमेन, या null जब डोमेन के पास कोई न हो।
status'none' | 'pending' | 'active' | 'failed'- `none` का अर्थ है कोई tracking डोमेन सेट नहीं है। `pending` का अर्थ है एक सेट है और वह कभी कोई जाँच पास नहीं कर पाया। `active` का अर्थ है नया मेल उसका उपयोग करता है। `failed` का अर्थ है वह पहले जाँच पास कर चुका था और तब से उपयोग से बाहर हो गया है।
activeboolean- ठीक तभी true, जब `status` `active` हो, यानी जब डोमेन से भेजे गए नए मेल के tracked लिंक और open पिक्सेल इस होस्ट का उपयोग करते हैं।
targetstring- वह पता जिस पर CNAME रिकॉर्ड इंगित करता है, केवल इसी tracking डोमेन के लिए तैयार किया गया। जब तक `host` null है, और जब तक नए होस्ट का पता तैयार हो रहा है, यह खाली स्ट्रिंग रहता है।
record{ type: 'CNAME'; name: string; value: string } | null- प्रकाशित करने वाला रिकॉर्ड, जिसका नाम `host` के अनुसार है और मान `target` है। जब कोई tracking डोमेन न हो, और जब तक नए होस्ट का पता तैयार हो रहा हो, तब null।
checkedAtstring | null- होस्ट की आख़िरी बार जाँच कब हुई, ISO-8601 में। पहली जाँच तक null।
verifiedAtstring | null- कोई जाँच आख़िरी बार कब पास हुई, ISO-8601 में। जिस होस्ट ने कभी कोई जाँच पास नहीं की उसके लिए null।
errorstring | null- पिछली जाँच में क्या मिला, ऐसे शब्दों में जिन पर डोमेन का मालिक कार्रवाई कर सके। जब पिछली जाँच पास हुई हो या कोई जाँच चली ही न हो, तब null। जिस होस्ट की एक या दो जाँचें विफल हुई हैं वह तब भी `active` रहता है और कारण यहीं रखता है।
storage ऑब्जेक्ट
files डोमेन storage में रिपोर्ट करता है, फ़ील्ड-दर-फ़ील्ड tracking जैसा ही। केवल यह अलग है कि नाम किस काम आता है: वहाँ active का अर्थ है कि डोमेन से भेजी गई फ़ाइलों के डाउनलोड लिंक उसी की ओर इंगित करते हैं।
hoststring | null- files डोमेन, या null जब डोमेन के पास कोई न हो।
status'none' | 'pending' | 'active' | 'failed'- `none` का अर्थ है कोई files डोमेन सेट नहीं है। `pending` का अर्थ है एक सेट है और वह कभी कोई जाँच पास नहीं कर पाया। `active` का अर्थ है नया मेल उसका उपयोग करता है। `failed` का अर्थ है वह पहले जाँच पास कर चुका था और तब से उपयोग से बाहर हो गया है।
activeboolean- ठीक तभी true, जब `status` `active` हो, यानी जब डोमेन से भेजी गई फ़ाइलों के डाउनलोड लिंक इस होस्ट का उपयोग करते हैं।
targetstring- वह पता जिस पर CNAME रिकॉर्ड इंगित करता है, केवल इसी files डोमेन के लिए तैयार किया गया। जब तक `host` null है, और जब तक नए होस्ट का पता तैयार हो रहा है, यह खाली स्ट्रिंग रहता है।
record{ type: 'CNAME'; name: string; value: string } | null- प्रकाशित करने वाला रिकॉर्ड, जिसका नाम `host` के अनुसार है और मान `target` है। जब कोई files डोमेन न हो, और जब तक नए होस्ट का पता तैयार हो रहा हो, तब null।
checkedAtstring | null- होस्ट की आख़िरी बार जाँच कब हुई, ISO-8601 में। पहली जाँच तक null।
verifiedAtstring | null- कोई जाँच आख़िरी बार कब पास हुई, ISO-8601 में। जिस होस्ट ने कभी कोई जाँच पास नहीं की उसके लिए null।
errorstring | null- पिछली जाँच में क्या मिला, ऐसे शब्दों में जिन पर डोमेन का मालिक कार्रवाई कर सके। जब पिछली जाँच पास हुई हो या कोई जाँच चली ही न हो, तब null। जिस होस्ट की एक या दो जाँचें विफल हुई हैं वह तब भी `active` रहता है और कारण यहीं रखता है।
होस्ट की जाँच कैसे होती है
दोनों नाम एक ही समय-सारणी पर जाँचे जाते हैं, और हर एक अपने आप में जाँचा जाता है।
- जिस होस्ट ने अभी तक कोई जाँच पास नहीं की, उसे पहले घंटे में हर 2 मिनट, पहले दिन में हर 10 मिनट, पहले सप्ताह में हर घंटे और उसके बाद हर 6 घंटे में जाँचा जाता है।
- सक्रिय होस्ट को हर 10 मिनट में जाँचा जाता है, और उस पर विफल जाँच को 1 मिनट बाद और फिर 2 मिनट बाद दोहराया जाता है।
- लगातार तीन विफल जाँचों के बाद, या जब उसकी आख़िरी पास हुई जाँच 2 घंटे से पुरानी हो जाए, सक्रिय होस्ट का उपयोग बंद हो जाता है। नया मेल तब डिफ़ॉल्ट होस्ट पर लौट जाता है, और जब तक कोई जाँच दोबारा पास न हो
statusfailedपढ़ा जाता है। जाँचें चलती रहती हैं, हर बार पहले से ज़्यादा अंतराल पर और अधिकतम एक घंटे के अंतर पर।
tracking डोमेन केवल tracking पथ देता है और files डोमेन केवल डाउनलोड पथ, और हर एक केवल उसी वर्कस्पेस के भेजे मेल के लिए उत्तर देता है जिसका वह है।
त्रुटियाँ
| स्थिति | type | code | कब |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | बॉडी वैध JSON नहीं है। |
| 403 | permission_error | insufficient_scope | कुंजी के पास domains:write नहीं है। |
| 404 | not_found_error | resource_not_found | इस वर्कस्पेस में उस id वाला कोई डोमेन नहीं है। |
| 409 | conflict_error | domain_not_verified | नया होस्ट तब भेजा गया जब receiving.verified false है और डोमेन का _openemail-challenge TXT रिकॉर्ड अभी प्रकाशित नहीं है। param वही फ़ील्ड है जिसमें वह आया, trackingHost या storageHost। |
| 409 | conflict_error | tracking_host_in_use | कोई दूसरा डोमेन पहले से इस होस्ट को अपने tracking डोमेन के रूप में उपयोग कर रहा है, होस्ट पहले से किसी files डोमेन के रूप में उपयोग में है, या डोमेन का tracking डोमेन किसी दूसरे OpenEmail सर्वर द्वारा संभाला जाता है। param trackingHost है। |
| 409 | conflict_error | storage_host_in_use | files डोमेन के लिए वही तीन स्थितियाँ: कोई दूसरा डोमेन पहले से इस होस्ट को अपने files डोमेन के रूप में उपयोग कर रहा है, होस्ट पहले से किसी tracking डोमेन के रूप में उपयोग में है, या यहाँ का files डोमेन किसी दूसरे OpenEmail सर्वर द्वारा संभाला जाता है। param storageHost है। |
| 422 | validation_error | invalid_tracking_host | होस्ट वैध hostname नहीं है, या अनुमत नहीं है: उसे डोमेन का कड़ाई से सबडोमेन होना चाहिए, और वह return path होस्ट bounce.<domain>, OpenEmail का कोई नाम, या मेल प्राप्त करने के लिए सेट किया गया डोमेन नहीं हो सकता। param trackingHost है। |
| 422 | validation_error | invalid_storage_host | वही नियम, files डोमेन पर अस्वीकृत। param storageHost है। |
| 422 | validation_error | unknown_parameter | trackingHost और storageHost के अलावा कोई बॉडी कुंजी। |
| 422 | validation_error | invalid_parameter | बॉडी JSON ऑब्जेक्ट नहीं है, या मौजूद कोई फ़ील्ड न string है न null, या 512 अक्षरों से आगे निकल जाती है। जिस बॉडी में इनमें से कोई फ़ील्ड नहीं है वह त्रुटि नहीं है: वह कुछ नहीं बदलती और 200 लौटाती है। |
| 422 | validation_error | capability_unsupported | कुंजी पूरे डोमेन के बजाय अलग-अलग पतों तक सीमित है, जबकि दोनों नाम डोमेन के हर पते पर लागू होते हैं। जिस कुंजी के domainAllowlist में यह डोमेन है वह इन्हें सेट कर सकती है। param domainAllowlist है। |