Aller à la documentation
API

Mettre à jour un domaine

Définit, revérifie ou supprime le domaine de suivi personnalisé et le domaine de fichiers personnalisé d'un domaine, les deux seules choses que cette API peut changer sur un domaine.

PATCHapi.openemail.uk/domains/{id}

Exécute le véritable appel sur votre espace de travail, avec votre propre clé.

PATCH /domains/{id}

Définit, revérifie ou supprime le domaine de suivi personnalisé et le domaine de fichiers personnalisé d'un domaine, les deux seules choses que cette API peut changer sur un domaine.

La requête

Un domaine peut avoir un domaine de suivi personnalisé et un domaine de fichiers personnalisé, chacun étant un sous-domaine de votre choix, comme links.acme.com et files.acme.com, dès qu'il est vérifié ou que son enregistrement TXT _openemail-challenge est publié. Il n'a pas besoin de recevoir déjà du courrier. En définir un prépare une adresse réservée à ce seul nom, rapportée dans target, et record est l'enregistrement CNAME qui fait pointer le nom vers elle. Une fois qu'une vérification passe, les liens suivis et le pixel d'ouverture des nouveaux messages issus du domaine utilisent https://links.acme.com/t/..., et les liens de téléchargement des fichiers envoyés depuis ce domaine utilisent https://files.acme.com/f/..., au lieu de l'hôte par défaut.

Paramètres

trackingHoststring | null
Le sous-domaine à utiliser pour les liens suivis et le pixel d'ouverture, 512 caractères au maximum. Il est débarrassé de ses espaces et passé en minuscules, et un `https://` ou `http://` en tête, un chemin et un point final sont retirés avant sa vérification. Une nouvelle valeur remplace le domaine de suivi actuel, la valeur actuelle relance la vérification, `null` ou une chaîne vide le supprime, et omettre le champ le laisse intact.
storageHoststring | null
Le sous-domaine à utiliser pour les liens de téléchargement de fichiers, nettoyé de la même façon et soumis aux mêmes 512 caractères. Une nouvelle valeur remplace le domaine de fichiers actuel, la valeur actuelle relance la vérification, `null` ou une chaîne vide le supprime, et omettre le champ le laisse intact.

Le corps est strict sur les clés et souple sur leur nombre. Toute clé autre que trackingHost et storageHost donne un 422 unknown_parameter, et un corps ne portant ni l'une ni l'autre est sans effet et répond 200 avec le domaine tel qu'il est. Les deux peuvent tenir dans un même appel, et elles sont appliquées dans l'ordre, trackingHost d'abord : un trackingHost refusé arrête l'appel avant que storageHost ne soit touché, et un storageHost refusé laisse en place la modification de trackingHost déjà effectuée. Envoyez-les séparément lorsque l'une ou l'autre doit tenir toute seule.

Définir un domaine de suivi et un domaine de fichiers

Nécessite domains:write. Chaque hôte est validé, enregistré et vérifié dans le même appel : la réponse porte donc déjà le résultat de cette première vérification. C'est le même corps 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" }'
Réponse
{  "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"}

Publiez tracking.record et storage.record chez votre fournisseur DNS sous forme de simples CNAME, tout proxy désactivé. La vérification résout chaque nom, puis demande à https://links.acme.com/t/v/<nonce> ou à https://files.acme.com/f/v/<nonce> une réponse signée par OpenEmail. Une redirection fait échouer la vérification, et un proxy placé devant le nom le peut aussi.

Une fois l'enregistrement résolu, une vérification peut indiquer que le nom pointe vers OpenEmail et attend d'être activé. C'est son certificat HTTPS qui est en cours d'émission : cela se passe de notre côté, ne demande rien de votre part et peut prendre un moment. Une fois terminé, la prochaine vérification réussie fait passer status à active.

Si l'adresse n'a pas pu être préparée pendant l'appel, record est null, target est une chaîne vide et error indique qu'elle est en cours de préparation. Cela se termine en quelques minutes sans nouvel appel : relisez donc le domaine avec GET /domains/{id} pour obtenir l'enregistrement.

Les deux noms sont indépendants. Un appel ne portant qu'un seul champ laisse l'autre objet exactement tel qu'il était : configurer les fichiers plus tard ne perturbe donc jamais un domaine de suivi déjà en service.

Revérifier, ou supprimer

Renvoyez l'hôte que le domaine possède déjà pour lancer la vérification tout de suite au lieu d'attendre la prochaine vérification planifiée. Si la dernière vérification, planifiée ou non, remonte à moins de 30 secondes, l'appel renvoie l'état enregistré sans changement. Envoyez null dans un champ pour supprimer ce nom, et omettez l'autre champ pour conserver le nom qu'il détient.

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

Les liens des messages déjà envoyés conservent l'hôte avec lequel ils sont partis, et cela vaut autant pour le lien de téléchargement d'un fichier que pour un lien suivi. Après avoir supprimé ou changé un nom, ces liens continuent de fonctionner tant que l'ancien enregistrement CNAME reste en place. Reconfigurer un nom peut lui donner un record différent : publiez donc celui que la réponse indique.

L'objet tracking

hoststring | null
Le domaine de suivi, ou null quand le domaine n'en a pas.
status'none' | 'pending' | 'active' | 'failed'
`none` signifie qu'aucun domaine de suivi n'est défini. `pending` signifie qu'il y en a un et qu'il n'a jamais passé de vérification. `active` signifie que les nouveaux messages l'utilisent. `failed` signifie qu'il a déjà passé une vérification et qu'il a depuis cessé d'être utilisé.
activeboolean
Vaut true exactement quand `status` est `active`, c'est-à-dire quand les liens suivis et le pixel d'ouverture des nouveaux messages issus du domaine utilisent l'hôte.
targetstring
L'adresse vers laquelle pointe l'enregistrement CNAME, préparée pour ce seul domaine de suivi. C'est une chaîne vide tant que `host` est null, et tant que l'adresse d'un nouvel hôte est encore en cours de préparation.
record{ type: 'CNAME'; name: string; value: string } | null
L'enregistrement à publier, nommé d'après `host` et ayant `target` pour valeur. Null lorsqu'il n'y a pas de domaine de suivi, et tant que l'adresse d'un nouvel hôte est encore en cours de préparation.
checkedAtstring | null
Date de la dernière vérification de l'hôte, ISO-8601. Null jusqu'à la première vérification.
verifiedAtstring | null
Date de la dernière vérification réussie, ISO-8601. Null pour un hôte qui n'en a jamais réussi.
errorstring | null
Ce qu'a constaté la dernière vérification, dans des termes sur lesquels le propriétaire du domaine peut agir. Null quand la dernière vérification a réussi ou qu'aucune n'a encore eu lieu. Un hôte qui a échoué à une ou deux vérifications reste `active` et porte ici la raison.

L'objet storage

Le domaine de fichiers se rapporte dans storage, champ pour champ identique à tracking. Seul l'usage du nom diffère : active y signifie que les liens de téléchargement des fichiers envoyés depuis le domaine pointent vers lui.

hoststring | null
Le domaine de fichiers, ou null quand le domaine n'en a pas.
status'none' | 'pending' | 'active' | 'failed'
`none` signifie qu'aucun domaine de fichiers n'est défini. `pending` signifie qu'il y en a un et qu'il n'a jamais passé de vérification. `active` signifie que les nouveaux messages l'utilisent. `failed` signifie qu'il a déjà passé une vérification et qu'il a depuis cessé d'être utilisé.
activeboolean
Vaut true exactement quand `status` est `active`, c'est-à-dire quand les liens de téléchargement des fichiers envoyés depuis le domaine utilisent l'hôte.
targetstring
L'adresse vers laquelle pointe l'enregistrement CNAME, préparée pour ce seul domaine de fichiers. C'est une chaîne vide tant que `host` est null, et tant que l'adresse d'un nouvel hôte est encore en cours de préparation.
record{ type: 'CNAME'; name: string; value: string } | null
L'enregistrement à publier, nommé d'après `host` et ayant `target` pour valeur. Null lorsqu'il n'y a pas de domaine de fichiers, et tant que l'adresse d'un nouvel hôte est encore en cours de préparation.
checkedAtstring | null
Date de la dernière vérification de l'hôte, ISO-8601. Null jusqu'à la première vérification.
verifiedAtstring | null
Date de la dernière vérification réussie, ISO-8601. Null pour un hôte qui n'en a jamais réussi.
errorstring | null
Ce qu'a constaté la dernière vérification, dans des termes sur lesquels le propriétaire du domaine peut agir. Null quand la dernière vérification a réussi ou qu'aucune n'a encore eu lieu. Un hôte qui a échoué à une ou deux vérifications reste `active` et porte ici la raison.

Comment l'hôte est vérifié

Les deux noms sont vérifiés selon le même calendrier, et chacun est vérifié pour lui-même.

  • Un hôte qui n'a pas encore passé de vérification est vérifié toutes les 2 minutes pendant sa première heure, toutes les 10 minutes pendant son premier jour, toutes les heures pendant sa première semaine, puis toutes les 6 heures.
  • Un hôte actif est vérifié toutes les 10 minutes, et une vérification échouée sur cet hôte est réessayée au bout d'1 minute, puis de 2.
  • Un hôte actif cesse d'être utilisé après trois vérifications échouées d'affilée, ou dès que sa dernière vérification réussie remonte à plus de 2 heures. Les nouveaux messages reviennent alors à l'hôte par défaut, et status affiche failed jusqu'à ce qu'une vérification passe de nouveau. Les vérifications se poursuivent, de plus en plus espacées et à une heure d'intervalle au maximum.

Un domaine de suivi ne sert que les chemins de suivi et un domaine de fichiers ne sert que les chemins de téléchargement, et chacun ne répond que pour le courrier envoyé par l'espace de travail qui le possède.

Erreurs

StatuttypecodeQuand
400invalid_request_errormalformed_jsonLe corps n'est pas du JSON valide.
403permission_errorinsufficient_scopeLa clé ne détient pas domains:write.
404not_found_errorresource_not_foundAucun domaine portant cet id dans cet espace de travail.
409conflict_errordomain_not_verifiedUn nouvel hôte a été envoyé alors que receiving.verified vaut false et que l'enregistrement TXT _openemail-challenge du domaine n'est pas encore publié. param est le champ par lequel il est arrivé, trackingHost ou storageHost.
409conflict_errortracking_host_in_useUn autre domaine utilise déjà cet hôte comme domaine de suivi, l'hôte est déjà utilisé comme domaine de fichiers, ou le domaine de suivi de ce domaine est géré par un autre serveur OpenEmail. param vaut trackingHost.
409conflict_errorstorage_host_in_useLes trois mêmes cas pour le domaine de fichiers : un autre domaine utilise déjà cet hôte comme domaine de fichiers, l'hôte est déjà utilisé comme domaine de suivi, ou le domaine de fichiers est ici géré par un autre serveur OpenEmail. param vaut storageHost.
422validation_errorinvalid_tracking_hostL'hôte n'est pas un nom d'hôte valide, ou n'est pas autorisé : il doit être un sous-domaine strict du domaine, et ne peut être ni l'hôte de chemin de retour bounce.<domain>, ni un nom appartenant à OpenEmail, ni un domaine configuré pour recevoir du courrier. param vaut trackingHost.
422validation_errorinvalid_storage_hostLes mêmes règles, refusées sur le domaine de fichiers. param vaut storageHost.
422validation_errorunknown_parameterUne clé du corps autre que trackingHost et storageHost.
422validation_errorinvalid_parameterLe corps n'est pas un objet JSON, ou un champ présent n'est ni une chaîne ni null, ou dépasse 512 caractères. Un corps ne portant aucun des deux champs n'est pas une erreur : il ne change rien et revient en 200.
422validation_errorcapability_unsupportedLa clé est restreinte à des adresses individuelles plutôt qu'à l'ensemble de ce domaine, alors que les deux noms s'appliquent à toutes les adresses du domaine. Une clé qui détient le domaine dans domainAllowlist peut les définir. param vaut domainAllowlist.