Configurer le DNS d'un domaine
Si OpenEmail écrit lui-même les enregistrements d'un domaine, via quelle zone connectée, et où en est chaque type d'enregistrement.
Exécute l'un des 3 appels sur votre espace de travail.
GET /domains/{id}/dns
Si OpenEmail écrit lui-même les enregistrements d'un domaine, via quelle zone connectée, et où en est chaque type d'enregistrement.
Lire la configuration
Nécessite domains:read. managing vaut true tant qu'OpenEmail écrit lui-même les enregistrements. zone indique quelle zone connectée répond pour le domaine : une seule donne resolved, plusieurs donnent ambiguous et demandent un choix, aucune ne le détient (none), ou les connexions n'ont pas pu être interrogées (unusable). Ajoutez ?refresh=true pour interroger de nouveau les fournisseurs.
curl "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/dns" -H "$AUTH"{ "object": "domain_dns", "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "managing": true, "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "connection": { "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "status": "active", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }] }, "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "zoneName": "acme.com", "zoneHolder": "Acme", "state": "ready", "steps": [ { "purpose": "mx", "ok": true, "detail": "MX records are in place.", "visibility": "public", "records": [] } ], "leftovers": [], "probe": null, "error": null, "syncedAt": "2026-09-30T08:01:12.000Z", "zone": { "kind": "resolved", "checkedAt": "2026-10-01T09:00:00.000Z", "cached": true, "candidate": { "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "subject": "[email protected]", "status": "active", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "account": { "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }, "zone": { "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "acme.com", "accountId": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "active": true, "status": "active", "type": "full", "nameServers": ["ana.ns.cloudflare.com", "bob.ns.cloudflare.com"], "covers": true } }, "candidates": [], "reason": null, "connected": null, "host": null, "blocked": [] }}leftovers liste les enregistrements qu'OpenEmail a écrits et n'a pas pu retirer, à supprimer à la main chez le fournisseur.
Choisir la zone
Nécessite domains:write. PUT /domains/{id}/dns avec { connectionId, zoneId } rattache le domaine à une zone quand plusieurs pourraient répondre pour lui. La zone doit couvrir le domaine, être active et accepter un enregistrement de test. Rien n'est encore écrit.
curl -X PUT "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/dns" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "zoneId": "023e105f4ecef8ad9ca31a8372d0c353" }'{ "object": "domain_dns", "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "managing": true, "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "connection": { "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "status": "active", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }] }, "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "zoneName": "acme.com", "zoneHolder": "Acme", "state": "awaiting-sync", "steps": [ { "purpose": "mx", "ok": true, "detail": "MX records are in place.", "visibility": "public", "records": [] } ], "leftovers": [], "probe": null, "error": null, "syncedAt": "2026-09-30T08:01:12.000Z", "zone": { "kind": "resolved", "checkedAt": "2026-10-01T09:00:00.000Z", "cached": true, "candidate": { "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "subject": "[email protected]", "status": "active", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "account": { "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }, "zone": { "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "acme.com", "accountId": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "active": true, "status": "active", "type": "full", "nameServers": ["ana.ns.cloudflare.com", "bob.ns.cloudflare.com"], "covers": true } }, "candidates": [], "reason": null, "connected": null, "host": null, "blocked": [] }}Une zone qui ne couvre pas le domaine donne un 422 invalid_parameter sur zoneId. Un domaine configuré via une autre zone donne 409 dns_zone_conflict, et une zone qui n'est pas active ou qui refuse l'enregistrement de test donne 409 dns_zone_unusable.
Un jeton d'accès OAuth a besoin d'un code de vérification pour cet appel. Tant que l'application n'en a pas vérifié un dans les 60 dernières minutes, l'appel répond 403 step_up_required et ne change rien. On ne le demande jamais à une clé API. La page Authentification montre comment demander un code et le vérifier.
Écrire les enregistrements
Nécessite domains:write. POST /domains/{id}/dns/sync écrit ou répare chaque enregistrement dont le domaine a besoin, comme le fait Synchroniser dans l'application, et rattache d'abord la zone quand une seule répond. Envoyez { "purpose": "dmarc" } pour n'écrire qu'un seul type d'enregistrement.
curl -X POST "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/dns/sync" -H "$AUTH"{ "object": "domain_dns_sync", "outcome": "synced", "message": null, "attached": false, "provision": { "outcome": "applied", "state": "ready", "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "proven": true, "ownership": "The ownership record is in place.", "written": [{ "purpose": "dmarc", "name": "_dmarc.acme.com", "type": "TXT", "mode": "created" }], "adopted": 6, "conflicts": [], "failures": [], "steps": [], "retired": [], "leftovers": [], "probe": null, "error": null }, "dns": { "object": "domain_dns", "domain": "acme.com", "managing": true, "state": "ready", "…": "…" }, "zone": { "kind": "resolved", "cached": false, "…": "…" }}Quand aucune zone ne répond seule, rien n'est écrit : outcome vaut refused, message explique pourquoi, et zone liste les zones parmi lesquelles choisir.
Une synchronisation déjà en cours sur le domaine donne 409 dns_busy, et un fournisseur qui refuse la requête donne 502 dns_provider_error. Un domaine qui attend ses enregistrements est vérifié dès qu'ils sont en place.
Un jeton d'accès OAuth a besoin d'un code de vérification pour cet appel. Tant que l'application n'en a pas vérifié un dans les 60 dernières minutes, l'appel répond 403 step_up_required et ne change rien. On ne le demande jamais à une clé API. La page Authentification montre comment demander un code et le vérifier.