Ugrás a dokumentációra
API

Domain frissítése

Beállítja, újraellenőrzi vagy eltávolítja a domain egyéni követési domainjét és egyéni fájldomainjét, azt a két dolgot, amit ez az API meg tud változtatni egy domainen.

PATCHapi.openemail.uk/domains/{id}

A valódi hívást futtatja le a munkaterületén, a saját kulcsával.

PATCH /domains/{id}

Beállítja, újraellenőrzi vagy eltávolítja a domain egyéni követési domainjét és egyéni fájldomainjét, azt a két dolgot, amit ez az API meg tud változtatni egy domainen.

A kérés

Egy domainhez egy egyéni követési domain és egy egyéni fájldomain tartozhat, mindkettő egy általad választott aldomainje, például links.acme.com és files.acme.com, amint a domain hitelesítve van vagy az _openemail-challenge TXT rekordja közzé van téve. Nem kell, hogy már fogadjon levelet. Az egyik beállítása kizárólag ehhez a névhez készít elő egy címet, amelyet a target jelent, a record pedig az a CNAME rekord, amely a nevet erre mutatja. Ha egy ellenőrzés átmegy, a domainről induló új levelekben a követett linkek és a megnyitási pixel a https://links.acme.com/t/... címet használja, a róla küldött fájlok letöltési linkjei pedig a https://files.acme.com/f/... címet, az alapértelmezett host helyett.

Paraméterek

trackingHoststring | null
A követett linkekhez és a megnyitási pixelhez használandó aldomain, legfeljebb 512 karakter. Levágjuk róla a szóközöket és kisbetűssé alakítjuk, az ellenőrzés előtt pedig eltávolítjuk a bevezető `https://` vagy `http://` részt, az útvonalat és a záró pontot. Új érték lecseréli a jelenlegi követési domaint, a jelenlegi érték újra lefuttatja az ellenőrzést, a `null` vagy az üres sztring eltávolítja, a mező kihagyása pedig érintetlenül hagyja.
storageHoststring | null
A fájlletöltési linkekhez használandó aldomain, ugyanúgy megtisztítva és ugyanahhoz az 512 karakterhez kötve. Új érték lecseréli a jelenlegi fájldomaint, a jelenlegi érték újra lefuttatja az ellenőrzést, a `null` vagy az üres sztring eltávolítja, a mező kihagyása pedig érintetlenül hagyja.

A törzs szigorú a kulcsokra és megengedő arra, hányat küldesz. A trackingHost és a storageHost mezőn kívüli bármely kulcs 422 unknown_parameter, az egyiket sem tartalmazó törzs pedig üres művelet, amely 200 választ ad a domainnel úgy, ahogy van. Mindkettő mehet egy hívásban, és sorrendben alkalmazzuk őket, elsőként a trackingHost mezőt: az elutasított trackingHost megállítja a hívást, mielőtt a storageHost sorra kerülne, az elutasított storageHost pedig a helyén hagyja a már elvégzett trackingHost változtatást. Küldd őket külön, ha bármelyiknek önmagában kell megállnia.

Követési domain és fájldomain beállítása

domains:write szükséges hozzá. Mindegyik hostot ugyanabban a hívásban ellenőrizzük, mentjük és teszteljük, így a válasz már az első ellenőrzés eredményét viszi. Ugyanaz a törzs, mint a GET /domains/{id} esetén.

curl
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" }'
Válasz
{  "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"}

A tracking.record és a storage.record rekordot sima CNAME-ként tedd közzé a DNS szolgáltatódnál, kikapcsolt proxyzással. Az ellenőrzés feloldja mindkét nevet, majd a https://links.acme.com/t/v/<nonce> vagy a https://files.acme.com/f/v/<nonce> címtől kér egy OpenEmail által aláírt választ. Az átirányítás megbuktatja az ellenőrzést, és ugyanígy megbuktathatja egy, a név elé tett proxy is.

Ha a rekord már feloldódik, az ellenőrzés jelentheti, hogy a név az OpenEmail felé mutat, és bekapcsolásra vár. Ez a HTTPS tanúsítványának kiállítása, ami a mi oldalunkon történik, tőled semmit nem igényel, és eltarthat egy ideig. Ha kész, a következő sikeres ellenőrzés active értékre állítja a status mezőt.

Ha a címet a hívás során nem sikerült előkészíteni, a record null, a target üres sztring, az error pedig azt mondja, hogy előkészítés alatt áll. Ez néhány percen belül, további hívás nélkül befejeződik, így a rekordért olvasd be újra a domaint a GET /domains/{id} hívással.

A két név független egymástól. Az egy mezőt vivő hívás a másik objektumot pontosan úgy hagyja, ahogy volt, így a fájlok későbbi beállítása soha nem zavarja meg a már élő követési domaint.

Újraellenőrzés vagy eltávolítás

Küldd el azt a hostot, amellyel a domain már rendelkezik, ha most akarod lefuttatni az ellenőrzést a következő ütemezett helyett. Ha az utolsó ellenőrzés, akár ütemezett, akár nem, kevesebb mint 30 másodperce futott, a hívás a tárolt állapotot adja vissza változatlanul. Küldj null értéket egy mezőben az adott név eltávolításához, a másik mezőt pedig hagyd ki, hogy megtartsa a nevét.

curl
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": null }'
tracking, eltávolítás után
{  "host": null,  "status": "none",  "active": false,  "target": "",  "record": null,  "checkedAt": null,  "verifiedAt": null,  "error": null}

A már elküldött levelekben lévő linkek megtartják azt a hostot, amellyel kimentek, és ez ugyanúgy vonatkozik egy fájl letöltési linkjére, mint egy követett linkre. Miután eltávolítasz vagy megváltoztatsz egy nevet, ezek a linkek addig működnek, amíg a régi CNAME rekord a helyén marad. Egy név újbóli beállítása más record értéket adhat, ezért azt tedd közzé, amelyet a válasz jelent.

A tracking objektum

hoststring | null
A követési domain, vagy null, ha a domainnek nincs ilyenje.
status'none' | 'pending' | 'active' | 'failed'
A `none` azt jelenti, hogy nincs beállítva követési domain. A `pending` azt, hogy be van állítva, és még soha nem ment át ellenőrzésen. Az `active` azt, hogy az új levelek használják. A `failed` azt, hogy korábban átment ellenőrzésen, és azóta kiesett a használatból.
activeboolean
Pontosan akkor igaz, amikor a `status` értéke `active`, vagyis amikor a domainről induló új levelekben a követett linkek és a megnyitási pixel ezt a hostot használják.
targetstring
Az a cím, amelyre a CNAME rekord mutat, kizárólag ehhez a követési domainhez előkészítve. Üres sztring, amíg a `host` null, és amíg egy új host címe még előkészítés alatt áll.
record{ type: 'CNAME'; name: string; value: string } | null
A közzéteendő rekord, a `host` szerint elnevezve, a `target` értékkel. Null, ha nincs követési domain, és amíg egy új host címe még előkészítés alatt áll.
checkedAtstring | null
Mikor ellenőrizték utoljára a hostot, ISO-8601 szerint. Null az első ellenőrzésig.
verifiedAtstring | null
Mikor ment át utoljára ellenőrzésen, ISO-8601 szerint. Null annál a hostnál, amelyik még soha nem ment át.
errorstring | null
Mit talált az utolsó ellenőrzés, olyan szavakkal, amelyekkel a domain tulajdonosa kezdeni tud valamit. Null, ha az utolsó ellenőrzés sikeres volt, vagy még egy sem futott. Az egy-két ellenőrzésen elbukott host még `active`, és itt viszi az okot.

A storage objektum

A fájldomain a storage objektumba jelent, mezőről mezőre ugyanúgy, mint a tracking. Csak az tér el, mire használjuk a nevet: ott az active azt jelenti, hogy a domainről küldött fájlok letöltési linkjei erre mutatnak.

hoststring | null
A fájldomain, vagy null, ha a domainnek nincs ilyenje.
status'none' | 'pending' | 'active' | 'failed'
A `none` azt jelenti, hogy nincs beállítva fájldomain. A `pending` azt, hogy be van állítva, és még soha nem ment át ellenőrzésen. Az `active` azt, hogy az új levelek használják. A `failed` azt, hogy korábban átment ellenőrzésen, és azóta kiesett a használatból.
activeboolean
Pontosan akkor igaz, amikor a `status` értéke `active`, vagyis amikor a domainről küldött fájlok letöltési linkjei ezt a hostot használják.
targetstring
Az a cím, amelyre a CNAME rekord mutat, kizárólag ehhez a fájldomainhez előkészítve. Üres sztring, amíg a `host` null, és amíg egy új host címe még előkészítés alatt áll.
record{ type: 'CNAME'; name: string; value: string } | null
A közzéteendő rekord, a `host` szerint elnevezve, a `target` értékkel. Null, ha nincs fájldomain, és amíg egy új host címe még előkészítés alatt áll.
checkedAtstring | null
Mikor ellenőrizték utoljára a hostot, ISO-8601 szerint. Null az első ellenőrzésig.
verifiedAtstring | null
Mikor ment át utoljára ellenőrzésen, ISO-8601 szerint. Null annál a hostnál, amelyik még soha nem ment át.
errorstring | null
Mit talált az utolsó ellenőrzés, olyan szavakkal, amelyekkel a domain tulajdonosa kezdeni tud valamit. Null, ha az utolsó ellenőrzés sikeres volt, vagy még egy sem futott. Az egy-két ellenőrzésen elbukott host még `active`, és itt viszi az okot.

Hogyan ellenőrizzük a hostot

Mindkét nevet ugyanazon ütemezés szerint ellenőrizzük, és mindegyiket önmagában.

  • Azt a hostot, amely még nem ment át ellenőrzésen, az első órában 2 percenként, az első napon 10 percenként, az első héten óránként, utána pedig 6 óránként ellenőrizzük.
  • Az aktív hostot 10 percenként ellenőrizzük, és egy rajta elbukott ellenőrzést 1 perc, majd 2 perc múlva megismétlünk.
  • Az aktív host három egymást követő sikertelen ellenőrzés után kiesik a használatból, vagy akkor, ha az utolsó sikeres ellenőrzése 2 óránál régebbi. Az új levél ilyenkor visszatér az alapértelmezett hostra, a status pedig failed marad, amíg egy ellenőrzés újra át nem megy. Az ellenőrzések folytatódnak, egyre ritkábban, legfeljebb óránként.

A követési domain csak követési útvonalakat szolgál ki, a fájldomain csak letöltési útvonalakat, és mindegyik kizárólag az őt birtokló munkaterület által küldött levelekre válaszol.

Hibák

StátusztypecodeMikor
400invalid_request_errormalformed_jsonA törzs nem érvényes JSON.
403permission_errorinsufficient_scopeA kulcs nem rendelkezik domains:write hatókörrel.
404not_found_errorresource_not_foundEbben a munkaterületben nincs ilyen azonosítójú domain.
409conflict_errordomain_not_verifiedÚj hostot küldtek, miközben a receiving.verified hamis, és a domain _openemail-challenge TXT rekordja még nincs közzétéve. A param az a mező, amelyben érkezett: trackingHost vagy storageHost.
409conflict_errortracking_host_in_useEgy másik domain már ezt a hostot használja követési domainként, a host már fájldomainként van használatban, vagy a domain követési domainjét egy másik OpenEmail szerver kezeli. A param értéke trackingHost.
409conflict_errorstorage_host_in_useUgyanaz a három eset a fájldomainre: egy másik domain már ezt a hostot használja fájldomainként, a host már követési domainként van használatban, vagy az itteni fájldomaint egy másik OpenEmail szerver kezeli. A param értéke storageHost.
422validation_errorinvalid_tracking_hostA host nem érvényes hostnév, vagy nem engedélyezett: a domain szigorú aldomainjének kell lennie, és nem lehet a bounce.<domain> visszaútvonal-host, az OpenEmailhez tartozó név vagy levélfogadásra beállított domain. A param értéke trackingHost.
422validation_errorinvalid_storage_hostUgyanazok a szabályok, a fájldomainen elutasítva. A param értéke storageHost.
422validation_errorunknown_parameterA trackingHost és a storageHost mezőtől eltérő törzskulcs.
422validation_errorinvalid_parameterA törzs nem JSON objektum, vagy egy jelen lévő mező se nem sztring, se nem null, vagy túllépi az 512 karaktert. Az egyik mezőt sem tartalmazó törzs nem hiba: semmit nem változtat, és 200 választ ad.
422validation_errorcapability_unsupportedA kulcs egyedi címekre van szűkítve, nem erre a teljes domainre, márpedig mindkét név a domain összes címére vonatkozik. Az a kulcs állíthatja be őket, amely a domaint a domainAllowlist listájában tartja. A param értéke domainAllowlist.