API

Actualizar un dominio

Configura, vuelve a comprobar o elimina el dominio de seguimiento personalizado y el dominio de archivos personalizado del dominio, las dos cosas de un dominio que esta API puede cambiar.

PATCHapi.openemail.uk/domains/{id}

Ejecuta la llamada real contra tu espacio de trabajo, con tu propia clave.

PATCH /domains/{id}

Configura, vuelve a comprobar o elimina el dominio de seguimiento personalizado y el dominio de archivos personalizado del dominio, las dos cosas de un dominio que esta API puede cambiar.

La solicitud

Un dominio puede tener un dominio de seguimiento personalizado y un dominio de archivos personalizado, cada uno un subdominio suyo que tú eliges, como links.acme.com y files.acme.com, en cuanto esté verificado o su registro TXT _openemail-challenge esté publicado. No hace falta que ya esté recibiendo correo. Configurar uno prepara una dirección solo para ese nombre, que se informa en target, y record es el registro CNAME que apunta el nombre hacia ella. Una vez que una comprobación pasa, los enlaces con seguimiento y el píxel de apertura del correo nuevo del dominio usan https://links.acme.com/t/..., y los enlaces de descarga de los archivos enviados desde él usan https://files.acme.com/f/..., en lugar del host por defecto.

Parámetros

trackingHoststring | null: El subdominio que se usará para los enlaces con seguimiento y el píxel de apertura, de 512 caracteres como máximo. Se le recortan los espacios y se pasa a minúsculas, y se le quitan un `https://` o `http://` iniciales, una ruta y un punto final antes de comprobarlo. Un valor nuevo sustituye al dominio de seguimiento actual, el valor actual vuelve a ejecutar la comprobación, `null` o una cadena vacía lo eliminan, y omitir el campo lo deja como está.
storageHoststring | null: El subdominio que se usará para los enlaces de descarga de archivos, depurado de la misma manera y sujeto a los mismos 512 caracteres. Un valor nuevo sustituye al dominio de archivos actual, el valor actual vuelve a ejecutar la comprobación, `null` o una cadena vacía lo eliminan, y omitir el campo lo deja como está.

El cuerpo es estricto con las claves y flexible con cuántas envías. Cualquier clave que no sea trackingHost ni storageHost es un 422 unknown_parameter, y un cuerpo que no lleve ninguna de las dos es una operación sin efecto que responde 200 con el dominio tal como está. Ambas pueden ir en una sola llamada, y se aplican en orden, trackingHost primero: un trackingHost rechazado detiene la llamada antes de tocar storageHost, y un storageHost rechazado deja en su sitio un cambio de trackingHost ya hecho. Envíalas por separado cuando cualquiera de las dos deba sostenerse por sí sola.

Configurar un dominio de seguimiento y un dominio de archivos

Requiere domains:write. Cada host se valida, se guarda y se comprueba en la misma llamada, así que la respuesta ya lleva el resultado de esa primera comprobación. Es el mismo cuerpo 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" }'

Respuesta

{  "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 y storage.record en tu proveedor de DNS como CNAME simples, con cualquier proxy desactivado. La comprobación resuelve cada nombre y después pide a https://links.acme.com/t/v/<nonce> o a https://files.acme.com/f/v/<nonce> una respuesta firmada por OpenEmail. Una redirección hace que la comprobación falle, y un proxy delante del nombre también puede hacerlo.

Una vez que el registro resuelve, una comprobación puede informar de que el nombre apunta a OpenEmail y está esperando a que lo activen. Eso es la emisión de su certificado HTTPS, que ocurre de nuestro lado, no necesita nada de ti y puede tardar un poco. Cuando termina, la siguiente comprobación que pase pone status en active.

Si la dirección no se pudo preparar durante la llamada, record es null, target es una cadena vacía y error dice que se está preparando. Termina en unos minutos sin otra llamada, así que vuelve a leer el dominio con GET /domains/{id} para obtener el registro.

Los dos nombres son independientes. Una llamada que lleva un campo deja el otro objeto exactamente como estaba, así que configurar los archivos más tarde nunca molesta a un dominio de seguimiento que ya está en marcha.

Volver a comprobarlo, o eliminarlo

Envía el host que el dominio ya tiene para ejecutar la comprobación ahora en lugar de esperar a la siguiente programada. Cuando la última comprobación, programada o no, se ejecutó hace menos de 30 segundos, la llamada devuelve el estado almacenado sin cambios. Envía null en un campo para eliminar ese nombre, y omite el otro campo para conservar el nombre que tiene.

curl

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

tracking, tras la eliminación

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

Los enlaces del correo ya enviado conservan el host con el que salieron, y eso vale tanto para el enlace de descarga de un archivo como para un enlace con seguimiento. Después de que elimines o cambies un nombre, esos enlaces siguen funcionando mientras el registro CNAME antiguo siga publicado. Volver a configurar un nombre puede darle un record distinto, así que publica el que informe la respuesta.

El objeto tracking

hoststring | null: El dominio de seguimiento, o null cuando el dominio no tiene ninguno.
status'none' | 'pending' | 'active' | 'failed': `none` significa que no hay ningún dominio de seguimiento configurado. `pending` significa que hay uno configurado y que nunca ha pasado una comprobación. `active` significa que el correo nuevo lo usa. `failed` significa que pasó una comprobación antes y desde entonces ha dejado de usarse.
activeboolean: True exactamente cuando `status` es `active`, que es cuando los enlaces con seguimiento y el píxel de apertura del correo nuevo del dominio usan el host.
targetstring: La dirección a la que apunta el registro CNAME, preparada solo para este dominio de seguimiento. Es una cadena vacía mientras `host` es null, y mientras la dirección de un host nuevo todavía se está preparando.
record{ type: 'CNAME'; name: string; value: string } | null: El registro que hay que publicar, con el nombre de `host` y `target` como valor. Null cuando no hay dominio de seguimiento, y mientras la dirección de un host nuevo todavía se está preparando.
checkedAtstring | null: Cuándo se comprobó el host por última vez, ISO-8601. Null hasta la primera comprobación.
verifiedAtstring | null: Cuándo pasó una comprobación por última vez, ISO-8601. Null para un host que nunca ha pasado ninguna.
errorstring | null: Qué encontró la última comprobación, en palabras sobre las que el propietario del dominio puede actuar. Null cuando la última comprobación pasó o cuando no se ha ejecutado ninguna. Un host que ha fallado una o dos comprobaciones sigue estando `active` y lleva aquí el motivo.

El objeto storage

El dominio de archivos informa en storage, campo por campo igual que tracking. Solo difiere para qué se usa el nombre: active ahí significa que los enlaces de descarga de los archivos enviados desde el dominio apuntan a él.

hoststring | null: El dominio de archivos, o null cuando el dominio no tiene ninguno.
status'none' | 'pending' | 'active' | 'failed': `none` significa que no hay ningún dominio de archivos configurado. `pending` significa que hay uno configurado y que nunca ha pasado una comprobación. `active` significa que el correo nuevo lo usa. `failed` significa que pasó una comprobación antes y desde entonces ha dejado de usarse.
activeboolean: True exactamente cuando `status` es `active`, que es cuando los enlaces de descarga de los archivos enviados desde el dominio usan el host.
targetstring: La dirección a la que apunta el registro CNAME, preparada solo para este dominio de archivos. Es una cadena vacía mientras `host` es null, y mientras la dirección de un host nuevo todavía se está preparando.
record{ type: 'CNAME'; name: string; value: string } | null: El registro que hay que publicar, con el nombre de `host` y `target` como valor. Null cuando no hay dominio de archivos, y mientras la dirección de un host nuevo todavía se está preparando.
checkedAtstring | null: Cuándo se comprobó el host por última vez, ISO-8601. Null hasta la primera comprobación.
verifiedAtstring | null: Cuándo pasó una comprobación por última vez, ISO-8601. Null para un host que nunca ha pasado ninguna.
errorstring | null: Qué encontró la última comprobación, en palabras sobre las que el propietario del dominio puede actuar. Null cuando la última comprobación pasó o cuando no se ha ejecutado ninguna. Un host que ha fallado una o dos comprobaciones sigue estando `active` y lleva aquí el motivo.

Cómo se comprueba el host

Los dos nombres se comprueban con la misma periodicidad, y cada uno se comprueba por su cuenta.

Un host que todavía no ha pasado una comprobación se comprueba cada 2 minutos durante su primera hora, cada 10 minutos durante su primer día, cada hora durante su primera semana y cada 6 horas a partir de ahí.
Un host activo se comprueba cada 10 minutos, y una comprobación fallida sobre él se reintenta al cabo de 1 minuto y después de 2.
Un host activo deja de usarse tras tres comprobaciones fallidas seguidas, o cuando su última comprobación superada tiene más de 2 horas. El correo nuevo vuelve entonces al host por defecto, y status marca failed hasta que una comprobación vuelva a pasar. Las comprobaciones siguen, cada vez más separadas y como mucho con una hora de distancia.

Un dominio de seguimiento solo sirve rutas de seguimiento y un dominio de archivos solo sirve rutas de descarga, y cada uno responde únicamente por el correo enviado por el espacio de trabajo que lo posee.

Errores

Estado	type	code	Cuándo
400	invalid_request_error	malformed_json	El cuerpo no es JSON válido.
403	permission_error	insufficient_scope	La clave no tiene `domains:write`.
404	not_found_error	resource_not_found	No hay ningún dominio con ese id en este espacio de trabajo.
409	conflict_error	domain_not_verified	Se envió un host nuevo mientras `receiving.verified` es false y el registro TXT `_openemail-challenge` del dominio todavía no está publicado. `param` es el campo por el que llegó, `trackingHost` o `storageHost`.
409	conflict_error	tracking_host_in_use	Otro dominio ya usa el host como su dominio de seguimiento, el host ya se usa como dominio de archivos, o el dominio de seguimiento del dominio lo gestiona otro servidor de OpenEmail. `param` es `trackingHost`.
409	conflict_error	storage_host_in_use	Los mismos tres casos para el dominio de archivos: otro dominio ya usa el host como su dominio de archivos, el host ya se usa como dominio de seguimiento, o el dominio de archivos de aquí lo gestiona otro servidor de OpenEmail. `param` es `storageHost`.
422	validation_error	invalid_tracking_host	El host no es un nombre de host válido, o no está permitido: debe ser un subdominio estricto del dominio, y no puede ser el host de la ruta de retorno `bounce.<domain>`, un nombre que pertenezca a OpenEmail ni un dominio configurado para recibir correo. `param` es `trackingHost`.
422	validation_error	invalid_storage_host	Las mismas reglas, rechazadas sobre el dominio de archivos. `param` es `storageHost`.
422	validation_error	unknown_parameter	Una clave del cuerpo que no sea `trackingHost` ni `storageHost`.
422	validation_error	invalid_parameter	El cuerpo no es un objeto JSON, o un campo presente no es ni una cadena ni null, o pasa de 512 caracteres. Un cuerpo que no lleva ninguno de los dos campos no es un error: no cambia nada y responde 200.
422	validation_error	capability_unsupported	La clave está restringida a direcciones sueltas y no a todo este dominio, y ambos nombres se aplican a todas las direcciones del dominio. Una clave que tenga el dominio en `domainAllowlist` sí puede configurarlos. `param` es `domainAllowlist`.