API

Actualitzar un domini

Estableix, torna a comprovar o elimina el domini de seguiment personalitzat i el domini de fitxers personalitzat del domini, les dues coses d'un domini que aquesta API pot canviar.

PATCHapi.openemail.uk/domains/{id}

Executa la crida real contra el teu espai de treball, amb la teva pròpia clau.

PATCH /domains/{id}

Estableix, torna a comprovar o elimina el domini de seguiment personalitzat i el domini de fitxers personalitzat del domini, les dues coses d'un domini que aquesta API pot canviar.

La sol·licitud

Un domini pot tenir un domini de seguiment personalitzat i un domini de fitxers personalitzat, cadascun un subdomini seu que tu triïs, com ara links.acme.com i files.acme.com, tan bon punt estigui verificat o tingui publicat el seu registre TXT _openemail-challenge. No cal que ja estigui rebent correu. Configurar-ne un prepara una adreça només per a aquest nom, indicada a target, i record és el registre CNAME que hi apunta el nom. Un cop passa una comprovació, els enllaços amb seguiment i el píxel d'obertura del correu nou del domini fan servir https://links.acme.com/t/..., i els enllaços de descàrrega dels fitxers que se n'envien fan servir https://files.acme.com/f/..., en comptes de l'amfitrió per defecte.

Paràmetres

trackingHoststring | null: El subdomini que s'ha de fer servir per als enllaços amb seguiment i el píxel d'obertura, com a màxim 512 caràcters. Es retalla i es passa a minúscules, i s'eliminen un `https://` o `http://` inicial, un camí i un punt final abans de comprovar-lo. Un valor nou substitueix el domini de seguiment actual, el valor actual torna a executar la comprovació, `null` o una cadena buida l'elimina, i ometre el camp el deixa estar.
storageHoststring | null: El subdomini que s'ha de fer servir per als enllaços de descàrrega de fitxers, netejat de la mateixa manera i sotmès als mateixos 512 caràcters. Un valor nou substitueix el domini de fitxers actual, el valor actual torna a executar la comprovació, `null` o una cadena buida l'elimina, i ometre el camp el deixa estar.

El cos és estricte amb les claus i relaxat amb quantes n'envies. Qualsevol clau que no sigui trackingHost i storageHost és un 422 unknown_parameter, i un cos que no porta cap de les dues és una operació nul·la que respon 200 amb el domini tal com està. Totes dues poden anar en una sola crida, i s'apliquen en ordre, primer trackingHost: un trackingHost rebutjat atura la crida abans de tocar storageHost, i un storageHost rebutjat deixa en peu un canvi de trackingHost ja fet. Envia'ls per separat quan qualsevol dels dos hagi de valer per si sol.

Configurar un domini de seguiment i un domini de fitxers

Requereix domains:write. Cada amfitrió es valida, es desa i es comprova a la mateixa crida, de manera que la resposta ja porta el resultat d'aquesta primera comprovació. És el mateix cos que 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" }'

Resposta

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

Publica tracking.record i storage.record al teu proveïdor de DNS com a CNAME simples, amb qualsevol proxi desactivat. La comprovació resol cada nom i després demana a https://links.acme.com/t/v/<nonce> o https://files.acme.com/f/v/<nonce> una resposta signada per OpenEmail. Una redirecció fa fallar la comprovació, i un proxi davant del nom també pot fer-la fallar.

Un cop el registre resol, una comprovació pot informar que el nom apunta a OpenEmail i espera ser activat. Això és l'emissió del seu certificat HTTPS, que passa al nostre costat, no necessita res de tu i pot trigar una mica. Quan s'acaba, la següent comprovació que passi posa status a active.

Si l'adreça no s'ha pogut preparar durant la crida, record és null, target és una cadena buida i error diu que s'està preparant. S'acaba en pocs minuts sense cap altra crida, així que torna a llegir el domini amb GET /domains/{id} per obtenir el registre.

Els dos noms són independents. Una crida que porta un camp deixa l'altre objecte exactament com estava, de manera que configurar els fitxers més endavant no destorba mai un domini de seguiment que ja funciona.

Torneu a comprovar-ho, o elimineu-lo

Envia l'amfitrió que el domini ja té per executar la comprovació ara en comptes d'esperar la següent programada. Quan l'última comprovació, programada o no, s'ha fet fa menys de 30 segons, la crida retorna l'estat desat sense canvis. Envia null en un camp per eliminar aquell nom, i omet l'altre camp per mantenir el nom que té.

curl

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

tracking, després de l'eliminació

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

Els enllaços dels correus ja enviats conserven l'amfitrió amb què van sortir, i això val tant per a l'enllaç de descàrrega d'un fitxer com per a un enllaç amb seguiment. Després d'eliminar o canviar un nom, aquests enllaços continuen funcionant mentre el registre CNAME antic es mantingui publicat. Tornar a configurar un nom li pot donar un record diferent, així que publiqueu el que indiqui la resposta.

L'objecte tracking

hoststring | null: El domini de seguiment, o null quan el domini no en té cap.
status'none' | 'pending' | 'active' | 'failed': `none` vol dir que no hi ha cap domini de seguiment configurat. `pending` vol dir que n'hi ha un de configurat que no ha superat mai cap comprovació. `active` vol dir que el correu nou l'utilitza. `failed` vol dir que abans havia superat una comprovació i que des d'aleshores ha deixat d'utilitzar-se.
activeboolean: Cert exactament quan `status` és `active`, que és quan els enllaços amb seguiment i el píxel d'obertura del correu nou enviat des del domini utilitzen l'amfitrió.
targetstring: L'adreça a què apunta el registre CNAME, preparada només per a aquest domini de seguiment. És una cadena buida mentre `host` és null, i mentre l'adreça d'un amfitrió nou encara s'està preparant.
record{ type: 'CNAME'; name: string; value: string } | null: El registre que cal publicar, amb el nom de `host` i amb `target` com a valor. Null quan no hi ha cap domini de seguiment, i mentre l'adreça d'un amfitrió nou encara s'està preparant.
checkedAtstring | null: Quan es va comprovar l'amfitrió per última vegada, ISO-8601. Null fins a la primera comprovació.
verifiedAtstring | null: Quan es va superar una comprovació per última vegada, ISO-8601. Null per a un amfitrió que no n'ha superat mai cap.
errorstring | null: Què va trobar l'última comprovació, en paraules sobre les quals el propietari del domini pugui actuar. Null quan l'última comprovació s'ha superat o quan encara no se n'ha executat cap. Un amfitrió que ha fallat una o dues comprovacions continua sent `active` i porta el motiu aquí.

L'objecte storage

El domini de fitxers s'informa dins de storage, camp per camp igual que tracking. L'única diferència és per a què s'utilitza el nom: allà active vol dir que els enllaços de descàrrega dels fitxers enviats des del domini hi apunten.

hoststring | null: El domini de fitxers, o null quan el domini no en té cap.
status'none' | 'pending' | 'active' | 'failed': `none` vol dir que no hi ha cap domini de fitxers configurat. `pending` vol dir que n'hi ha un de configurat que no ha superat mai cap comprovació. `active` vol dir que el correu nou l'utilitza. `failed` vol dir que abans havia superat una comprovació i que des d'aleshores ha deixat d'utilitzar-se.
activeboolean: Cert exactament quan `status` és `active`, que és quan els enllaços de descàrrega dels fitxers enviats des del domini utilitzen l'amfitrió.
targetstring: L'adreça a què apunta el registre CNAME, preparada només per a aquest domini de fitxers. És una cadena buida mentre `host` és null, i mentre l'adreça d'un amfitrió nou encara s'està preparant.
record{ type: 'CNAME'; name: string; value: string } | null: El registre que cal publicar, amb el nom de `host` i amb `target` com a valor. Null quan no hi ha cap domini de fitxers, i mentre l'adreça d'un amfitrió nou encara s'està preparant.
checkedAtstring | null: Quan es va comprovar l'amfitrió per última vegada, ISO-8601. Null fins a la primera comprovació.
verifiedAtstring | null: Quan es va superar una comprovació per última vegada, ISO-8601. Null per a un amfitrió que no n'ha superat mai cap.
errorstring | null: Què va trobar l'última comprovació, en paraules sobre les quals el propietari del domini pugui actuar. Null quan l'última comprovació s'ha superat o quan encara no se n'ha executat cap. Un amfitrió que ha fallat una o dues comprovacions continua sent `active` i porta el motiu aquí.

Com es comprova l'amfitrió

Tots dos noms es comproven amb la mateixa periodicitat, i cadascun es comprova pel seu compte.

Un amfitrió que encara no ha superat cap comprovació es comprova cada 2 minuts durant la primera hora, cada 10 minuts durant el primer dia, cada hora durant la primera setmana i cada 6 hores a partir d'aleshores.
Un amfitrió actiu es comprova cada 10 minuts, i una comprovació fallida s'hi reintenta al cap d'1 minut i després al cap de 2.
Un amfitrió actiu deixa d'utilitzar-se després de tres comprovacions fallides seguides, o quan l'última comprovació superada té més de 2 hores. Aleshores el correu nou torna a l'amfitrió per defecte, i status indica failed fins que una comprovació torni a passar. Les comprovacions continuen, cada vegada més espaiades i com a màxim amb una hora de separació.

Un domini de seguiment només serveix rutes de seguiment i un domini de fitxers només serveix rutes de descàrrega, i cadascun només respon per al correu enviat per l'espai de treball que n'és propietari.

Errors

Estat	type	code	Quan
400	invalid_request_error	malformed_json	El cos no és JSON vàlid.
403	permission_error	insufficient_scope	La clau no té `domains:write`.
404	not_found_error	resource_not_found	No hi ha cap domini amb aquest id en aquest espai de treball.
409	conflict_error	domain_not_verified	S'ha enviat un amfitrió nou mentre `receiving.verified` és false i el registre TXT `_openemail-challenge` del domini encara no està publicat. `param` és el camp pel qual va arribar, `trackingHost` o `storageHost`.
409	conflict_error	tracking_host_in_use	Un altre domini ja utilitza l'amfitrió com a domini de seguiment, l'amfitrió ja s'utilitza com a domini de fitxers, o el domini de seguiment d'aquest domini el gestiona un servidor d'OpenEmail diferent. `param` és `trackingHost`.
409	conflict_error	storage_host_in_use	Els mateixos tres casos per al domini de fitxers: un altre domini ja utilitza l'amfitrió com a domini de fitxers, l'amfitrió ja s'utilitza com a domini de seguiment, o el domini de fitxers d'aquí el gestiona un servidor d'OpenEmail diferent. `param` és `storageHost`.
422	validation_error	invalid_tracking_host	L'amfitrió no és un nom d'amfitrió vàlid, o no està permès: ha de ser un subdomini estricte del domini, i no pot ser l'amfitrió de la ruta de retorn `bounce.<domain>`, ni un nom que pertanyi a OpenEmail, ni un domini configurat per rebre correu. `param` és `trackingHost`.
422	validation_error	invalid_storage_host	Les mateixes regles, rebutjades al domini de fitxers. `param` és `storageHost`.
422	validation_error	unknown_parameter	Una clau del cos diferent de `trackingHost` i `storageHost`.
422	validation_error	invalid_parameter	El cos no és un objecte JSON, o un camp que hi és present no és ni string ni null, o supera els 512 caràcters. Un cos que no porti cap dels dos camps no és cap error: no canvia res i retorna 200.
422	validation_error	capability_unsupported	La clau està restringida a adreces concretes en lloc de a tot aquest domini, i tots dos noms s'apliquen a totes les adreces del domini. Una clau que tingui el domini a `domainAllowlist` els pot establir. `param` és `domainAllowlist`.