Atjaunināt domēnu
Iestata, pārbauda vēlreiz vai noņem domēna pielāgoto izsekošanas domēnu un pielāgoto failu domēnu — divas lietas, ko šis API domēnā var mainīt.
Izpilda īstu izsaukumu pret jūsu darbvietu, ar jūsu paša atslēgu.
PATCH /domains/{id}
Iestata, pārbauda vēlreiz vai noņem domēna pielāgoto izsekošanas domēnu un pielāgoto failu domēnu — divas lietas, ko šis API domēnā var mainīt.
Pieprasījums
Domēnam var būt viens pielāgots izsekošanas domēns un viens pielāgots failu domēns, katrs no tiem — jūsu izvēlēts tā apakšdomēns, piemēram, links.acme.com un files.acme.com, tiklīdz tas ir verificēts vai ir publicēts tā _openemail-challenge TXT ieraksts. Tam vēl nav jāsaņem pasts. Viena iestatīšana sagatavo adresi tieši šim nosaukumam, ko ziņo target, un record ir CNAME ieraksts, kas nosaukumu uz to norāda. Kad pārbaude ir izturēta, izsekotās saites un atvēršanas pikselis jaunā pastā no šī domēna izmanto https://links.acme.com/t/..., bet lejupielādes saites no tā sūtītajiem failiem — https://files.acme.com/f/..., nevis noklusējuma resursdatoru.
Parametri
trackingHoststring | null- Apakšdomēns, ko izmantot izsekotajām saitēm un atvēršanas pikselim, ne vairāk kā 512 rakstzīmes. Tas tiek apcirsts no atstarpēm un pārveidots mazajiem burtiem, un pirms pārbaudes tiek noņemts sākuma `https://` vai `http://`, ceļš un beigu punkts. Jauna vērtība aizstāj pašreizējo izsekošanas domēnu, pašreizējā vērtība palaiž pārbaudi no jauna, `null` vai tukša virkne to noņem, bet lauka izlaišana to atstāj neskartu.
storageHoststring | null- Apakšdomēns, ko izmantot failu lejupielādes saitēm, sakopts tāpat un ar to pašu 512 rakstzīmju ierobežojumu. Jauna vērtība aizstāj pašreizējo failu domēnu, pašreizējā vērtība palaiž pārbaudi no jauna, `null` vai tukša virkne to noņem, bet lauka izlaišana to atstāj neskartu.
Pieprasījuma ķermenis ir strikts attiecībā uz atslēgām un pielaidīgs attiecībā uz to, cik daudz tās sūtāt. Jebkura atslēga, kas nav trackingHost vai storageHost, ir 422 unknown_parameter, un ķermenis, kurā nav nevienas no tām, ir tukšs izsaukums, kas atbild ar 200 un domēnu tādu, kāds tas ir. Abas var iet vienā izsaukumā, un tās tiek piemērotas secībā, vispirms trackingHost: noraidīts trackingHost aptur izsaukumu, pirms storageHost tiek aiztikts, bet noraidīts storageHost atstāj jau veiktās trackingHost izmaiņas spēkā. Sūtiet tās atsevišķi, kad kādai no tām jāstāv pašai par sevi.
Iestatīt izsekošanas domēnu un failu domēnu
Nepieciešams domains:write. Katrs resursdators tiek validēts, saglabāts un pārbaudīts vienā izsaukumā, tāpēc atbilde jau nes šīs pirmās pārbaudes rezultātu. Tas ir tas pats ķermenis, ko dod 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"}Publicējiet tracking.record un storage.record pie sava DNS pakalpojumu sniedzēja kā vienkāršus CNAME ierakstus ar izslēgtu starpniekošanu. Pārbaude atrisina katru nosaukumu, tad prasa https://links.acme.com/t/v/<nonce> vai https://files.acme.com/f/v/<nonce> atbildi, ko parakstījis OpenEmail. Novirzīšana pārbaudi izgāž, un to var izdarīt arī starpniekserveris nosaukuma priekšā.
Kad ieraksts atrisinās, pārbaude var ziņot, ka nosaukums norāda uz OpenEmail un gaida ieslēgšanu. Tas ir tā HTTPS sertifikāts, kas tiek izsniegts mūsu pusē, neprasa neko no jums un var aizņemt kādu laiku. Kad tas izdarīts, nākamā izturētā pārbaude iestata status uz active.
Ja izsaukuma laikā adresi nevarēja sagatavot, record ir null, target ir tukša virkne un error saka, ka tā tiek gatavota. Tas pabeidzas dažu minūšu laikā bez vēl viena izsaukuma, tāpēc nolasiet domēnu vēlreiz ar GET /domains/{id}, lai iegūtu ierakstu.
Abi nosaukumi ir neatkarīgi. Izsaukums ar vienu lauku atstāj otru objektu tieši tādu, kāds tas bija, tāpēc failu domēna iestatīšana vēlāk nekad netraucē jau dzīvu izsekošanas domēnu.
Pārbaudīt vēlreiz vai noņemt
Nosūtiet resursdatoru, kāds domēnam jau ir, lai palaistu pārbaudi tagad, nevis gaidītu nākamo ieplānoto. Ja pēdējā pārbaude — ieplānota vai ne — notikusi mazāk nekā pirms 30 sekundēm, izsaukums atgriež uzglabāto stāvokli neizmainītu. Sūtiet laukā null, lai noņemtu šo nosaukumu, un izlaidiet otru lauku, lai paturētu tā nosaukumu.
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}Saites jau nosūtītā pastā saglabā to resursdatoru, ar kuru tās aizgāja, un tas attiecas gan uz faila lejupielādes saiti, gan uz izsekoto saiti. Pēc nosaukuma noņemšanas vai maiņas šīs saites turpina darboties tik ilgi, kamēr vecais CNAME ieraksts paliek vietā. Nosaukuma atkārtota iestatīšana tam var dot citu record, tāpēc publicējiet to, ko ziņo atbilde.
tracking objekts
hoststring | null- Izsekošanas domēns vai null, ja domēnam tāda nav.
status'none' | 'pending' | 'active' | 'failed'- `none` nozīmē, ka izsekošanas domēns nav iestatīts. `pending` nozīmē, ka viens ir iestatīts un nekad nav izturējis pārbaudi. `active` nozīmē, ka jaunais pasts to izmanto. `failed` nozīmē, ka tas kādreiz pārbaudi izturēja un kopš tā laika ir izkritis no lietošanas.
activeboolean- True tieši tad, kad `status` ir `active`, proti, kad izsekotās saites un atvēršanas pikselis jaunā pastā no šī domēna izmanto šo resursdatoru.
targetstring- Adrese, uz kuru norāda CNAME ieraksts, sagatavota tieši šim izsekošanas domēnam. Tā ir tukša virkne, kamēr `host` ir null, kā arī kamēr adrese jaunam resursdatoram vēl tiek gatavota.
record{ type: 'CNAME'; name: string; value: string } | null- Publicējamais ieraksts, nosaukts pēc `host` ar `target` kā vērtību. Null, ja izsekošanas domēna nav, kā arī kamēr adrese jaunam resursdatoram vēl tiek gatavota.
checkedAtstring | null- Kad resursdators pēdējoreiz pārbaudīts, ISO-8601. Null līdz pirmajai pārbaudei.
verifiedAtstring | null- Kad pārbaude pēdējoreiz izturēta, ISO-8601. Null resursdatoram, kas nekad nav izturējis nevienu.
errorstring | null- Ko atklāja pēdējā pārbaude, vārdos, uz kuriem domēna īpašnieks var rīkoties. Null, ja pēdējā pārbaude izturēta vai neviena vēl nav notikusi. Resursdators, kas izgāzis vienu vai divas pārbaudes, joprojām ir `active` un šeit nes iemeslu.
storage objekts
Failu domēns ziņo objektā storage, lauku pa laukam tāpat kā tracking. Atšķiras tikai tas, kam nosaukumu izmanto: active tur nozīmē, ka lejupielādes saites failiem, kas sūtīti no šī domēna, norāda uz to.
hoststring | null- Failu domēns vai null, ja domēnam tāda nav.
status'none' | 'pending' | 'active' | 'failed'- `none` nozīmē, ka failu domēns nav iestatīts. `pending` nozīmē, ka viens ir iestatīts un nekad nav izturējis pārbaudi. `active` nozīmē, ka jaunais pasts to izmanto. `failed` nozīmē, ka tas kādreiz pārbaudi izturēja un kopš tā laika ir izkritis no lietošanas.
activeboolean- True tieši tad, kad `status` ir `active`, proti, kad lejupielādes saites failiem, kas sūtīti no šī domēna, izmanto šo resursdatoru.
targetstring- Adrese, uz kuru norāda CNAME ieraksts, sagatavota tieši šim failu domēnam. Tā ir tukša virkne, kamēr `host` ir null, kā arī kamēr adrese jaunam resursdatoram vēl tiek gatavota.
record{ type: 'CNAME'; name: string; value: string } | null- Publicējamais ieraksts, nosaukts pēc `host` ar `target` kā vērtību. Null, ja failu domēna nav, kā arī kamēr adrese jaunam resursdatoram vēl tiek gatavota.
checkedAtstring | null- Kad resursdators pēdējoreiz pārbaudīts, ISO-8601. Null līdz pirmajai pārbaudei.
verifiedAtstring | null- Kad pārbaude pēdējoreiz izturēta, ISO-8601. Null resursdatoram, kas nekad nav izturējis nevienu.
errorstring | null- Ko atklāja pēdējā pārbaude, vārdos, uz kuriem domēna īpašnieks var rīkoties. Null, ja pēdējā pārbaude izturēta vai neviena vēl nav notikusi. Resursdators, kas izgāzis vienu vai divas pārbaudes, joprojām ir `active` un šeit nes iemeslu.
Kā resursdators tiek pārbaudīts
Abi nosaukumi tiek pārbaudīti pēc viena grafika, un katrs tiek pārbaudīts atsevišķi.
- Resursdators, kas vēl nav izturējis pārbaudi, pirmajā stundā tiek pārbaudīts ik pēc 2 minūtēm, pirmajā dienā ik pēc 10 minūtēm, pirmajā nedēļā reizi stundā un pēc tam ik pēc 6 stundām.
- Aktīvs resursdators tiek pārbaudīts ik pēc 10 minūtēm, un neizdevusies pārbaude tam tiek atkārtota pēc 1 minūtes un pēc tam pēc 2.
- Aktīvs resursdators pārstāj tikt lietots pēc trim neizdevušamies pārbaudēm pēc kārtas vai tad, kad tā pēdējā izturētā pārbaude ir vecāka par 2 stundām. Jaunais pasts tad atgriežas pie noklusējuma resursdatora, un
statusrādafailed, līdz kāda pārbaude atkal izdodas. Pārbaudes turpinās, katru reizi retāk un ne retāk kā reizi stundā.
Izsekošanas domēns apkalpo tikai izsekošanas ceļus, bet failu domēns — tikai lejupielādes ceļus, un katrs atbild tikai par pastu, ko sūtījusi darbvieta, kurai tas pieder.
Kļūdas
| Statuss | type | code | Kad |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | Ķermenis nav derīgs JSON. |
| 403 | permission_error | insufficient_scope | Atslēgai nav domains:write. |
| 404 | not_found_error | resource_not_found | Šajā darbvietā nav domēna ar tādu id. |
| 409 | conflict_error | domain_not_verified | Jauns resursdators tika nosūtīts, kamēr receiving.verified ir false un domēna _openemail-challenge TXT ieraksts vēl nav publicēts. param ir lauks, kurā tas atnāca, — trackingHost vai storageHost. |
| 409 | conflict_error | tracking_host_in_use | Cits domēns jau izmanto šo resursdatoru kā savu izsekošanas domēnu, resursdators jau tiek lietots kā failu domēns, vai arī šī domēna izsekošanas domēnu pārvalda cits OpenEmail serveris. param ir trackingHost. |
| 409 | conflict_error | storage_host_in_use | Tie paši trīs gadījumi failu domēnam: cits domēns jau izmanto šo resursdatoru kā savu failu domēnu, resursdators jau tiek lietots kā izsekošanas domēns, vai arī failu domēnu šeit pārvalda cits OpenEmail serveris. param ir storageHost. |
| 422 | validation_error | invalid_tracking_host | Resursdators nav derīgs resursdatora nosaukums vai nav atļauts: tam jābūt stingram domēna apakšdomēnam, un tas nedrīkst būt atgriešanas ceļa resursdators bounce.<domain>, nosaukums, kas pieder OpenEmail, vai domēns, kas iestatīts pasta saņemšanai. param ir trackingHost. |
| 422 | validation_error | invalid_storage_host | Tie paši noteikumi, noraidīti failu domēnam. param ir storageHost. |
| 422 | validation_error | unknown_parameter | Ķermeņa atslēga, kas nav trackingHost vai storageHost. |
| 422 | validation_error | invalid_parameter | Ķermenis nav JSON objekts, vai klātesošs lauks nav ne string, ne null, vai pārsniedz 512 rakstzīmes. Ķermenis, kurā nav neviena no laukiem, nav kļūda: tas neko nemaina un atgriežas ar 200. |
| 422 | validation_error | capability_unsupported | Atslēga ir sašaurināta līdz atsevišķām adresēm, nevis līdz visam šim domēnam, bet abi nosaukumi attiecas uz katru domēna adresi. Atslēga, kurai domēns ir domainAllowlist, tos drīkst iestatīt. param ir domainAllowlist. |