---
title: "DNS connections"
description: "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."
url: "https://openemail.uk/docs/api/dns-connections"
area: "API"
category: "Mailbox"
---

# 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.

`GET /dns-connections`

**Also documents:** `GET /dns-connections/{id}`, `DELETE /dns-connections/{id}`

## 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**

```
curl "$OE/dns-connections" -H "$AUTH"
```

**Response**

```
{
  "object": "list",
  "configured": true,
  "data": [
    {
      "object": "dns_connection",
      "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d",
      "provider": "cloudflare",
      "subject": "ana@acme.com",
      "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**

```
curl "$OE/dns-connections/dnsl_3f9a1c2e7b4d4e6f8a0b2c3d" -H "$AUTH"
```

**Response**

```
{
  "object": "dns_connection",
  "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d",
  "provider": "cloudflare",
  "subject": "ana@acme.com",
  "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**

```
curl -X DELETE "$OE/dns-connections/dnsl_3f9a1c2e7b4d4e6f8a0b2c3d" -H "$AUTH"
```

**Response**

```
{
  "object": "dns_connection",
  "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d",
  "provider": "cloudflare",
  "subject": "ana@acme.com",
  "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.

## Reference

- [`GET /dns-connections`](https://openemail.uk/docs/api/reference/domains#get-dns-connections): full reference
- [`GET /dns-connections/{id}`](https://openemail.uk/docs/api/reference/domains#get-dns-connections-id): full reference
- [`DELETE /dns-connections/{id}`](https://openemail.uk/docs/api/reference/domains#delete-dns-connections-id): full reference