DNS connections
The DNS provider accounts connected to the workspace, through which OpenEmail writes the records of a domain itself. One is connected in the app, because the provider asks the person to sign in.
Runs any of 3 calls on your workspace.
GET /dns-connections
The DNS provider accounts connected to the workspace, through which OpenEmail writes the records of a domain itself. One is connected in the app, because the provider asks the person to sign in.
List the connections
Needs domains:read. Every connection, disconnected ones included, with the domains each one serves. configured is false when this server cannot connect a provider at all.
curl "$OE/dns-connections" -H "$AUTH"{ "object": "list", "configured": true, "data": [ { "object": "dns_connection", "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "provider": "cloudflare", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "status": "active", "lastVerifiedAt": "2026-09-30T08:00:00.000Z", "lastError": null, "createdAt": "2026-09-01T10:12:00.000Z", "domains": [ { "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "zoneName": "acme.com", "state": "ready", "records": 7, "keepsMail": true, "busy": false } ], "records": 7, "removable": false } ]}status is active while OpenEmail may write through the connection, needs-reauth when the provider wants the account connected again in the app, revoked once it was disconnected and error when the last call failed.
Read one connection
Needs domains:read. GET /dns-connections/{id} adds what disconnecting it would leave behind: busy names the domains a sync is running on, and keepsMail the verified domains that stop receiving mail once their records come down.
curl "$OE/dns-connections/dnsl_3f9a1c2e7b4d4e6f8a0b2c3d" -H "$AUTH"{ "object": "dns_connection", "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "provider": "cloudflare", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "status": "active", "lastVerifiedAt": "2026-09-30T08:00:00.000Z", "lastError": null, "createdAt": "2026-09-01T10:12:00.000Z", "domains": [ { "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "zoneName": "acme.com", "state": "ready", "records": 7, "keepsMail": true, "busy": false } ], "records": 7, "removable": false, "busy": [], "keepsMail": ["acme.com"]}Disconnect a connection
Needs domains:write. DELETE /dns-connections/{id} takes the records written through the connection down, detaches every domain it serves and revokes it at the provider. A verified domain whose records come down stops receiving mail, so read the connection first.
curl -X DELETE "$OE/dns-connections/dnsl_3f9a1c2e7b4d4e6f8a0b2c3d" -H "$AUTH"{ "object": "dns_connection", "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "provider": "cloudflare", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "status": "revoked", "lastVerifiedAt": "2026-09-30T08:00:00.000Z", "lastError": null, "createdAt": "2026-09-01T10:12:00.000Z", "removed": false, "confirmed": true, "detached": { "domains": 1, "detached": 1, "removed": 7, "rewritten": 0, "pending": 0, "left": [] }}Deleting a connection that is already disconnected removes it from the list, once no domain and no record is left on it, and removed is true. With something still on it, the call is 409 dns_connection_in_use.
A sync running on one of its domains is refused with 409 dns_busy, and nothing is revoked.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member also needs workspace:manage in their role.
An OAuth access token needs a verification code for this call. Until the app has verified one in the last 60 minutes, the call answers 403 step_up_required and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.