API

Aktualizace domény

Nastaví, znovu zkontroluje nebo odstraní vlastní doménu pro sledování a vlastní doménu pro soubory – dvě věci, které toto API na doméně umí změnit.

PATCHapi.openemail.uk/domains/{id}

Spustí skutečné volání proti vašemu pracovnímu prostoru, s vaším vlastním klíčem.

PATCH /domains/{id}

Nastaví, znovu zkontroluje nebo odstraní vlastní doménu pro sledování a vlastní doménu pro soubory – dvě věci, které toto API na doméně umí změnit.

Požadavek

Doména může mít jednu vlastní doménu pro sledování a jednu vlastní doménu pro soubory, každou jako svou subdoménu podle vaší volby, třeba links.acme.com a files.acme.com, jakmile je ověřená nebo je publikovaný její TXT záznam _openemail-challenge. Nemusí ještě přijímat poštu. Nastavením se pro tento název připraví samostatná adresa, kterou hlásí target, a record je CNAME záznam, který na ni název nasměruje. Jakmile kontrola projde, sledované odkazy a pixel pro otevření v nové poště z této domény používají https://links.acme.com/t/... a odkazy ke stažení souborů z ní odeslaných používají https://files.acme.com/f/... místo výchozího hosta.

Parametry

trackingHoststring | null: Subdoména, která se má použít pro sledované odkazy a pixel pro otevření, nejvýše 512 znaků. Ořízne se, převede na malá písmena a před kontrolou se z ní odstraní úvodní `https://` nebo `http://`, cesta i koncová tečka. Nová hodnota nahradí současnou doménu pro sledování, současná hodnota spustí kontrolu znovu, `null` nebo prázdný řetězec ji odstraní a vynechání pole ji nechá být.
storageHoststring | null: Subdoména, která se má použít pro odkazy ke stažení souborů, čištěná stejným způsobem a držená na stejných 512 znacích. Nová hodnota nahradí současnou doménu pro soubory, současná hodnota spustí kontrolu znovu, `null` nebo prázdný řetězec ji odstraní a vynechání pole ji nechá být.

Tělo je přísné na klíče a shovívavé k tomu, kolik jich pošlete. Jakýkoli klíč jiný než trackingHost a storageHost je 422 unknown_parameter a tělo, které nenese ani jeden z nich, nic neudělá a odpoví 200 s doménou v současném stavu. Oba mohou jít v jednom volání a uplatňují se v pořadí, trackingHost první: odmítnutý trackingHost zastaví volání dřív, než se sáhne na storageHost, a odmítnutý storageHost ponechá už provedenou změnu trackingHost na místě. Když má kterýkoli z nich obstát sám o sobě, posílejte je odděleně.

Nastavení domény pro sledování a domény pro soubory

Vyžaduje domains:write. Každý host se ve stejném volání ověří, uloží a zkontroluje, takže odpověď už nese výsledek této první kontroly. Je to totéž tělo jako u GET /domains/{id}.

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" }'

Odpověď

{  "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 a storage.record publikujte u svého DNS providera jako obyčejné CNAME záznamy, s vypnutým proxy. Kontrola každý název přeloží a pak si na https://links.acme.com/t/v/<nonce> nebo https://files.acme.com/f/v/<nonce> vyžádá odpověď podepsanou OpenEmail. Přesměrování kontrolu shodí a shodit ji může i proxy před tím názvem.

Jakmile se záznam přeloží, může kontrola oznámit, že název míří na OpenEmail a čeká na zapnutí. To se vydává jeho HTTPS certifikát, což probíhá na naší straně, nic od vás nevyžaduje a chvíli to může trvat. Až to bude hotové, první kontrola, která projde, nastaví status na active.

Pokud se adresu během volání nepodařilo připravit, record je null, target je prázdný řetězec a error říká, že se připravuje. Dokončí se to během několika minut bez dalšího volání, takže si doménu kvůli záznamu načtěte znovu přes GET /domains/{id}.

Oba názvy jsou nezávislé. Volání nesoucí jedno pole nechá druhý objekt přesně tak, jak byl, takže pozdější nastavení souborů nikdy nenaruší doménu pro sledování, která už běží.

Opětovná kontrola nebo odstranění

Pošlete hosta, kterého doména už má, a kontrola se spustí hned, místo čekání na další naplánovanou. Pokud poslední kontrola – plánovaná i neplánovaná – proběhla před méně než 30 vteřinami, volání vrátí uložený stav beze změny. Posláním null v poli daný název odstraníte a vynecháním druhého pole v něm ponecháte název, který drží.

curl

curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": null }'

tracking, po odstranění

{  "host": null,  "status": "none",  "active": false,  "target": "",  "record": null,  "checkedAt": null,  "verifiedAt": null,  "error": null}

Odkazy v už odeslané poště si ponechají hosta, se kterým odešly, a to platí pro odkaz ke stažení souboru stejně jako pro sledovaný odkaz. Poté, co název odstraníte nebo změníte, tyto odkazy fungují dál, dokud zůstane na místě starý CNAME záznam. Opětovné nastavení názvu mu může dát jiný record, takže publikujte ten, který hlásí odpověď.

Objekt tracking

hoststring | null: Doména pro sledování, nebo null, když doména žádnou nemá.
status'none' | 'pending' | 'active' | 'failed': `none` znamená, že není nastavená žádná doména pro sledování. `pending` znamená, že nastavená je a nikdy neprošla kontrolou. `active` znamená, že ji nová pošta používá. `failed` znamená, že kontrolou dřív prošla a od té doby se přestala používat.
activeboolean: True přesně tehdy, když je `status` `active`, tedy když sledované odkazy a pixel pro otevření v nové poště z této domény používají tohoto hosta.
targetstring: Adresa, na kterou CNAME záznam míří, připravená výhradně pro tuto doménu pro sledování. Je to prázdný řetězec, dokud je `host` null a dokud se adresa pro nového hosta teprve připravuje.
record{ type: 'CNAME'; name: string; value: string } | null: Záznam, který se má publikovat, pojmenovaný podle `host` a s hodnotou `target`. Null, když žádná doména pro sledování není, a dokud se adresa pro nového hosta teprve připravuje.
checkedAtstring | null: Kdy byl host naposledy zkontrolován, ISO-8601. Null až do první kontroly.
verifiedAtstring | null: Kdy naposledy kontrola prošla, ISO-8601. Null u hosta, který nikdy žádnou neprošel.
errorstring | null: Co poslední kontrola zjistila, slovy, podle kterých může vlastník domény jednat. Null, když poslední kontrola prošla nebo když zatím žádná neproběhla. Host, který neuspěl v jedné nebo dvou kontrolách, je stále `active` a nese tady důvod.

Objekt storage

Doména pro soubory se hlásí do storage, pole po poli stejně jako tracking. Liší se jen to, k čemu se název používá: active tam znamená, že na něj míří odkazy ke stažení souborů odeslaných z této domény.

hoststring | null: Doména pro soubory, nebo null, když doména žádnou nemá.
status'none' | 'pending' | 'active' | 'failed': `none` znamená, že není nastavená žádná doména pro soubory. `pending` znamená, že nastavená je a nikdy neprošla kontrolou. `active` znamená, že ji nová pošta používá. `failed` znamená, že kontrolou dřív prošla a od té doby se přestala používat.
activeboolean: True přesně tehdy, když je `status` `active`, tedy když odkazy ke stažení souborů odeslaných z této domény používají tohoto hosta.
targetstring: Adresa, na kterou CNAME záznam míří, připravená výhradně pro tuto doménu pro soubory. Je to prázdný řetězec, dokud je `host` null a dokud se adresa pro nového hosta teprve připravuje.
record{ type: 'CNAME'; name: string; value: string } | null: Záznam, který se má publikovat, pojmenovaný podle `host` a s hodnotou `target`. Null, když žádná doména pro soubory není, a dokud se adresa pro nového hosta teprve připravuje.
checkedAtstring | null: Kdy byl host naposledy zkontrolován, ISO-8601. Null až do první kontroly.
verifiedAtstring | null: Kdy naposledy kontrola prošla, ISO-8601. Null u hosta, který nikdy žádnou neprošel.
errorstring | null: Co poslední kontrola zjistila, slovy, podle kterých může vlastník domény jednat. Null, když poslední kontrola prošla nebo když zatím žádná neproběhla. Host, který neuspěl v jedné nebo dvou kontrolách, je stále `active` a nese tady důvod.

Jak se host kontroluje

Oba názvy se kontrolují podle stejného rozvrhu a každý se kontroluje samostatně.

Host, který ještě neprošel kontrolou, se kontroluje každé 2 minuty v první hodině, každých 10 minut první den, každou hodinu první týden a poté každých 6 hodin.
Aktivní host se kontroluje každých 10 minut a neúspěšná kontrola se u něj opakuje po 1 minutě a pak po 2.
Aktivní host se přestane používat po třech neúspěšných kontrolách za sebou nebo jakmile je jeho poslední úspěšná kontrola starší než 2 hodiny. Nová pošta se pak vrátí k výchozímu hostovi a status hlásí failed, dokud nějaká kontrola znovu neprojde. Kontroly pokračují dál, pokaždé s delším odstupem, nejvýše však hodinu.

Doména pro sledování obsluhuje jen sledovací cesty a doména pro soubory jen cesty ke stažení, a každá odpovídá jen pro poštu odeslanou workspace, kterému patří.

Chyby

Stav	type	code	Kdy
400	invalid_request_error	malformed_json	Tělo není platný JSON.
403	permission_error	insufficient_scope	Klíč nemá `domains:write`.
404	not_found_error	resource_not_found	V tomto workspace není žádná doména s tímto id.
409	conflict_error	domain_not_verified	Byl poslán nový host, zatímco `receiving.verified` je false a TXT záznam `_openemail-challenge` dané domény ještě není publikovaný. `param` je pole, ve kterém přišel, `trackingHost` nebo `storageHost`.
409	conflict_error	tracking_host_in_use	Hosta už jiná doména používá jako svou doménu pro sledování, host se už používá jako doména pro soubory, nebo doménu pro sledování této domény spravuje jiný server OpenEmail. `param` je `trackingHost`.
409	conflict_error	storage_host_in_use	Tytéž tři případy pro doménu pro soubory: hosta už jiná doména používá jako svou doménu pro soubory, host se už používá jako doména pro sledování, nebo zdejší doménu pro soubory spravuje jiný server OpenEmail. `param` je `storageHost`.
422	validation_error	invalid_tracking_host	Host není platný název hosta nebo není povolený: musí být striktní subdoménou dané domény a nesmí to být host návratové cesty `bounce.<domain>`, název patřící OpenEmail ani doména nastavená pro příjem pošty. `param` je `trackingHost`.
422	validation_error	invalid_storage_host	Tatáž pravidla, odmítnuto u domény pro soubory. `param` je `storageHost`.
422	validation_error	unknown_parameter	Klíč v těle jiný než `trackingHost` a `storageHost`.
422	validation_error	invalid_parameter	Tělo není JSON objekt, nebo přítomné pole není ani string, ani null, nebo přesahuje 512 znaků. Tělo, které nenese ani jedno z polí, chybou není: nic nezmění a vrátí se 200.
422	validation_error	capability_unsupported	Klíč je zúžen na jednotlivé adresy, ne na celou tuto doménu, a oba názvy platí pro každou adresu na doméně. Nastavit je může klíč, který má doménu v `domainAllowlist`. `param` je `domainAllowlist`.