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.
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 -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"}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 -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}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
statuspedigfailedmarad, 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átusz | type | code | Mikor |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | A törzs nem érvényes JSON. |
| 403 | permission_error | insufficient_scope | A kulcs nem rendelkezik domains:write hatókörrel. |
| 404 | not_found_error | resource_not_found | Ebben a munkaterületben nincs ilyen azonosítójú domain. |
| 409 | conflict_error | domain_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. |
| 409 | conflict_error | tracking_host_in_use | Egy 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. |
| 409 | conflict_error | storage_host_in_use | Ugyanaz 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. |
| 422 | validation_error | invalid_tracking_host | A 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. |
| 422 | validation_error | invalid_storage_host | Ugyanazok a szabályok, a fájldomainen elutasítva. A param értéke storageHost. |
| 422 | validation_error | unknown_parameter | A trackingHost és a storageHost mezőtől eltérő törzskulcs. |
| 422 | validation_error | invalid_parameter | A 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. |
| 422 | validation_error | capability_unsupported | A 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. |