Përditësoni një domen
Cakton, rikontrollon ose heq domenin e personalizuar të gjurmimit dhe domenin e personalizuar të skedarëve të një domeni — dy gjërat që ky API mund t’i ndryshojë te një domen.
Ekzekuton thirrjen reale kundrejt hapësirës suaj të punës, me çelësin tuaj.
PATCH /domains/{id}
Cakton, rikontrollon ose heq domenin e personalizuar të gjurmimit dhe domenin e personalizuar të skedarëve të një domeni — dy gjërat që ky API mund t’i ndryshojë te një domen.
Kërkesa
Një domen mund të ketë një domen të personalizuar gjurmimi dhe një domen të personalizuar skedarësh, secili një nëndomen i tij që e zgjidhni ju, si links.acme.com dhe files.acme.com, sapo ai të jetë i verifikuar ose të jetë publikuar rekordi i tij TXT _openemail-challenge. Nuk është e nevojshme që ai të pranojë ende postë. Caktimi i njërit prej tyre përgatit një adresë vetëm për atë emër, e raportuar te target, dhe record është rekordi CNAME që e drejton emrin drejt saj. Sapo të kalojë një kontroll, lidhjet e gjurmuara dhe pikseli i hapjes në postën e re nga domeni përdorin https://links.acme.com/t/..., ndërsa lidhjet e shkarkimit për skedarët e dërguar prej tij përdorin https://files.acme.com/f/..., në vend të hostit të parazgjedhur.
Parametrat
trackingHoststring | null- Nëndomeni që do të përdoret për lidhjet e gjurmuara dhe pikselin e hapjes, me së shumti 512 karaktere. Atij i hiqen hapësirat anësore dhe kthehet në shkronja të vogla, ndërsa një `https://` ose `http://` në fillim, shtegu dhe pika në fund hiqen para se të kontrollohet. Një vlerë e re zëvendëson domenin aktual të gjurmimit, vlera aktuale e nis kontrollin sërish, `null` ose një varg bosh e heq atë, ndërsa lënia e fushës jashtë e lë atë siç është.
storageHoststring | null- Nëndomeni që do të përdoret për lidhjet e shkarkimit të skedarëve, i pastruar në të njëjtën mënyrë dhe i mbajtur te të njëjtat 512 karaktere. Një vlerë e re zëvendëson domenin aktual të skedarëve, vlera aktuale e nis kontrollin sërish, `null` ose një varg bosh e heq atë, ndërsa lënia e fushës jashtë e lë atë siç është.
Trupi është i rreptë për çelësat dhe i lirshëm për sa prej tyre dërgoni. Çdo çelës tjetër veç trackingHost dhe storageHost është një 422 unknown_parameter, ndërsa një trup që nuk mbart asnjërin prej tyre nuk bën asgjë dhe përgjigjet me 200 me domenin ashtu siç është. Të dy mund të shkojnë në një thirrje të vetme dhe zbatohen me radhë, trackingHost i pari: një trackingHost i refuzuar e ndal thirrjen para se të preket storageHost, ndërsa një storageHost i refuzuar e lë në fuqi ndryshimin e trackingHost që u krye tashmë. Dërgojini veç e veç kur secili duhet të qëndrojë më vete.
Caktoni një domen gjurmimi dhe një domen skedarësh
Kërkon domains:write. Çdo host validohet, ruhet dhe kontrollohet në të njëjtën thirrje, ndaj përgjigjja e mbart tashmë rezultatin e atij kontrolli të parë. Është i njëjti trup si te 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"}Publikoni tracking.record dhe storage.record te ofruesi juaj i DNS-së si rekorde CNAME të thjeshta, me çdo proxy të fikur. Kontrolli e zgjidh secilin emër, pastaj i kërkon https://links.acme.com/t/v/<nonce> ose https://files.acme.com/f/v/<nonce> një përgjigje të nënshkruar nga OpenEmail. Një ridrejtim e rrëzon kontrollin, po ashtu edhe një proxy përpara emrit.
Sapo rekordi të zgjidhet, një kontroll mund të raportojë se emri drejton te OpenEmail dhe po pret të aktivizohet. Kjo është lëshimi i certifikatës së tij HTTPS, që ndodh nga ana jonë, nuk kërkon asgjë prej jush dhe mund të zgjasë pak. Sapo të përfundojë, kontrolli i parë që kalon e vendos status në active.
Nëse adresa nuk mundi të përgatitej gjatë thirrjes, record është null, target është një varg bosh dhe error thotë se ajo po përgatitet. Kjo përfundon brenda pak minutash pa një thirrje tjetër, ndaj lexojeni domenin sërish me GET /domains/{id} për rekordin.
Të dy emrat janë të pavarur. Një thirrje që mbart njërën fushë e lë objektin tjetër saktësisht siç ishte, ndaj konfigurimi i skedarëve më vonë nuk e prek kurrë një domen gjurmimi që është tashmë aktiv.
Rikontrolloni, ose hiqeni
Dërgoni hostin që domeni e ka tashmë për ta nisur kontrollin tani, në vend që të prisni të radhëve të planifikuar. Kur kontrolli i fundit, i planifikuar ose jo, ka ndodhur më pak se 30 sekonda më parë, thirrja e kthen gjendjen e ruajtur të pandryshuar. Dërgoni null në një fushë për ta hequr atë emër dhe lëreni fushën tjetër jashtë për të mbajtur emrin që ajo përmban.
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}Lidhjet në postën e dërguar tashmë e ruajnë hostin me të cilin dolën, dhe kjo vlen për lidhjen e shkarkimit të një skedari njësoj si për një lidhje të gjurmuar. Pasi të hiqni ose të ndryshoni një emër, ato lidhje vazhdojnë të funksionojnë për sa kohë rekordi i vjetër CNAME mbetet i publikuar. Rikonfigurimi i një emri mund t’i japë një record të ndryshëm, ndaj publikoni atë që raporton përgjigjja.
Objekti tracking
hoststring | null- Domeni i gjurmimit, ose null kur domeni nuk ka asnjë.
status'none' | 'pending' | 'active' | 'failed'- `none` do të thotë se nuk është caktuar asnjë domen gjurmimi. `pending` do të thotë se është caktuar një dhe nuk ka kaluar kurrë një kontroll. `active` do të thotë se posta e re e përdor. `failed` do të thotë se kishte kaluar një kontroll më parë dhe që atëherë ka dalë nga përdorimi.
activeboolean- E vërtetë pikërisht kur `status` është `active`, domethënë kur lidhjet e gjurmuara dhe pikseli i hapjes në postën e re nga domeni e përdorin hostin.
targetstring- Adresa te e cila drejton rekordi CNAME, e përgatitur vetëm për këtë domen gjurmimi. Është varg bosh derisa `host` është null, si dhe derisa adresa për një host të ri është ende duke u përgatitur.
record{ type: 'CNAME'; name: string; value: string } | null- Rekordi që duhet publikuar, i emërtuar sipas `host` dhe me `target` si vlerë. Null kur nuk ka domen gjurmimi, si dhe derisa adresa për një host të ri është ende duke u përgatitur.
checkedAtstring | null- Kur u kontrollua hosti për herë të fundit, ISO-8601. Null deri te kontrolli i parë.
verifiedAtstring | null- Kur kaloi një kontroll për herë të fundit, ISO-8601. Null për një host që nuk ka kaluar kurrë asnjë.
errorstring | null- Çfarë gjeti kontrolli i fundit, me fjalë mbi të cilat pronari i domenit mund të veprojë. Null kur kontrolli i fundit kaloi ose kur nuk ka ndodhur ende asnjë. Një host që ka rrëzuar një ose dy kontrolle është ende `active` dhe e mbart arsyen këtu.
Objekti storage
Domeni i skedarëve raporton te storage, fushë për fushë njësoj si tracking. Ndryshon vetëm ajo për çfarë përdoret emri: active atje do të thotë se lidhjet e shkarkimit për skedarët e dërguar nga domeni drejtojnë te ai.
hoststring | null- Domeni i skedarëve, ose null kur domeni nuk ka asnjë.
status'none' | 'pending' | 'active' | 'failed'- `none` do të thotë se nuk është caktuar asnjë domen skedarësh. `pending` do të thotë se është caktuar një dhe nuk ka kaluar kurrë një kontroll. `active` do të thotë se posta e re e përdor. `failed` do të thotë se kishte kaluar një kontroll më parë dhe që atëherë ka dalë nga përdorimi.
activeboolean- E vërtetë pikërisht kur `status` është `active`, domethënë kur lidhjet e shkarkimit për skedarët e dërguar nga domeni e përdorin hostin.
targetstring- Adresa te e cila drejton rekordi CNAME, e përgatitur vetëm për këtë domen skedarësh. Është varg bosh derisa `host` është null, si dhe derisa adresa për një host të ri është ende duke u përgatitur.
record{ type: 'CNAME'; name: string; value: string } | null- Rekordi që duhet publikuar, i emërtuar sipas `host` dhe me `target` si vlerë. Null kur nuk ka domen skedarësh, si dhe derisa adresa për një host të ri është ende duke u përgatitur.
checkedAtstring | null- Kur u kontrollua hosti për herë të fundit, ISO-8601. Null deri te kontrolli i parë.
verifiedAtstring | null- Kur kaloi një kontroll për herë të fundit, ISO-8601. Null për një host që nuk ka kaluar kurrë asnjë.
errorstring | null- Çfarë gjeti kontrolli i fundit, me fjalë mbi të cilat pronari i domenit mund të veprojë. Null kur kontrolli i fundit kaloi ose kur nuk ka ndodhur ende asnjë. Një host që ka rrëzuar një ose dy kontrolle është ende `active` dhe e mbart arsyen këtu.
Si kontrollohet hosti
Të dy emrat kontrollohen me të njëjtin orar dhe secili kontrollohet më vete.
- Një host që nuk ka kaluar ende një kontroll kontrollohet çdo 2 minuta në orën e parë, çdo 10 minuta në ditën e parë, çdo orë në javën e parë dhe çdo 6 orë më pas.
- Një host aktiv kontrollohet çdo 10 minuta, ndërsa një kontroll i rrëzuar mbi të riprovohet pas 1 minute e më pas pas 2 minutash.
- Një host aktiv del nga përdorimi pas tre kontrollesh të rrëzuar me radhë, ose sapo kontrolli i tij i fundit i kaluar të jetë më i vjetër se 2 orë. Posta e re kthehet atëherë te hosti i parazgjedhur dhe
statuslexonfailedderisa të kalojë sërish një kontroll. Kontrollet vazhdojnë, me intervale gjithnjë e më të gjata, por jo më shumë se një orë.
Një domen gjurmimi u shërben vetëm shtigjeve të gjurmimit dhe një domen skedarësh vetëm shtigjeve të shkarkimit, dhe secili përgjigjet vetëm për postën e dërguar nga hapësira e punës që e zotëron.
Gabimet
| Statusi | type | code | Kur |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | Trupi nuk është JSON i vlefshëm. |
| 403 | permission_error | insufficient_scope | Çelësi nuk e mban domains:write. |
| 404 | not_found_error | resource_not_found | Nuk ka asnjë domen me atë id në këtë hapësirë pune. |
| 409 | conflict_error | domain_not_verified | U dërgua një host i ri ndërkohë që receiving.verified është false dhe rekordi TXT _openemail-challenge i domenit nuk është publikuar ende. param është fusha nga e cila erdhi, trackingHost ose storageHost. |
| 409 | conflict_error | tracking_host_in_use | Një domen tjetër e përdor tashmë hostin si domenin e vet të gjurmimit, hosti është tashmë në përdorim si domen skedarësh, ose domeni i gjurmimit i këtij domeni menaxhohet nga një server tjetër OpenEmail. param është trackingHost. |
| 409 | conflict_error | storage_host_in_use | Të njëjtat tri raste për domenin e skedarëve: një domen tjetër e përdor tashmë hostin si domenin e vet të skedarëve, hosti është tashmë në përdorim si domen gjurmimi, ose domeni i skedarëve këtu menaxhohet nga një server tjetër OpenEmail. param është storageHost. |
| 422 | validation_error | invalid_tracking_host | Hosti nuk është emër hosti i vlefshëm, ose nuk lejohet: duhet të jetë një nëndomen i mirëfilltë i domenit dhe nuk mund të jetë hosti i shtegut të kthimit bounce.<domain>, një emër që i përket OpenEmail-it ose një domen i konfiguruar për të pranuar postë. param është trackingHost. |
| 422 | validation_error | invalid_storage_host | Të njëjtat rregulla, të refuzuara te domeni i skedarëve. param është storageHost. |
| 422 | validation_error | unknown_parameter | Një çelës i trupit tjetër veç trackingHost dhe storageHost. |
| 422 | validation_error | invalid_parameter | Trupi nuk është objekt JSON, ose një fushë e pranishme nuk është as varg as null, ose i kalon 512 karakteret. Një trup që nuk mbart asnjërën fushë nuk është gabim: nuk ndryshon asgjë dhe kthehet me 200. |
| 422 | validation_error | capability_unsupported | Çelësi është ngushtuar te adresa të veçanta dhe jo te i gjithë ky domen, ndërsa të dy emrat vlejnë për çdo adresë të domenit. Një çelës që e mban domenin te domainAllowlist mund t’i caktojë. param është domainAllowlist. |