---
title: "openemail.dns_connections"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/python/reference/dns-connections"
area: "Python"
category: "Reference"
---

# openemail.dns_connections

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

The DNS provider accounts connected to the workspace, through which OpenEmail writes the records of a domain itself: list them, read what disconnecting one would leave behind, and disconnect it. Connecting one is done in the app, because the provider asks the person to sign in.

### `dns_connections.list()`

List the DNS provider accounts connected to the workspace

```python
def list(
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DnsConnectionListResource
```

Returns every DNS provider account connected to the workspace, through which OpenEmail writes the records of a domain itself, as the Providers tab of the domains page in the app shows them. Each one names the domains it serves, how many records OpenEmail wrote through it and still keeps, and whether it is `active`, needs connecting again (`needs-reauth`) or was disconnected (`revoked`).

`configured` is `False` when this server cannot connect a provider at all. A connection is made in the app, because the provider asks the person to sign in, so there is no method to create one.

Scopes: `domains:read`.

**Parameters**

- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DnsConnectionListResource`, a dict with `configured` and every connection in `data`, disconnected ones included.

**Example**

```python
from openemail import openemail

connections = openemail.dns_connections.list()

if not connections['configured']:
    print('This server cannot connect a DNS provider')

for connection in connections['data']:
    print(connection['subject'], connection['status'], len(connection['domains']), 'domains')
```

**Notes**

- A GET is retried automatically on network failure, on 408 and 5xx responses, and on a 429 that carries `Retry-After`, up to the client's `max_retries`.

Also available in: API [`GET /dns-connections`](https://openemail.uk/docs/api/reference/domains#get-dns-connections); TypeScript [`dnsConnections.list()`](https://openemail.uk/docs/sdk/reference/dns-connections#list); Ruby [`dns_connections.list`](https://openemail.uk/docs/ruby/reference/dns-connections#list); CLI [`openemail dns-connections list`](https://openemail.uk/docs/cli/reference/dns-connections#dns-connections-list).

### `dns_connections.get()`

Read a DNS connection and what disconnecting it would leave behind

```python
def get(
    id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DnsConnectionDetailResource
```

Returns one connection with what disconnecting it would do: the domains it serves, the records OpenEmail wrote through it, `busy` for the domains a sync is running on right now, which hold a disconnect back until it ends, and `keepsMail` for the verified domains that stop receiving mail once their records come down.

Scopes: `domains:read`.

**Parameters**

- `id` (`str`, required): A connection id from `list`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DnsConnectionDetailResource`, the connection with its `domains`, `records`, `busy` and `keepsMail`.

**Example**

```python
from openemail import openemail

connection = openemail.dns_connections.get('dnsl_3f9a1c2e7b4d4e6f8a0b2c3d')

if connection['busy']:
    print('A sync is running on', ', '.join(connection['busy']))

if connection['keepsMail']:
    print('These stop receiving mail:', ', '.join(connection['keepsMail']))
```

**Notes**

- A connection id that is not in this workspace is a 404 `resource_not_found`.
- A GET is retried automatically on network failure, on 408 and 5xx responses, and on a 429 that carries `Retry-After`, up to the client's `max_retries`.

Also available in: API [`GET /dns-connections/{id}`](https://openemail.uk/docs/api/reference/domains#get-dns-connections-id); TypeScript [`dnsConnections.get()`](https://openemail.uk/docs/sdk/reference/dns-connections#get); Ruby [`dns_connections.get`](https://openemail.uk/docs/ruby/reference/dns-connections#get); CLI [`openemail dns-connections get`](https://openemail.uk/docs/cli/reference/dns-connections#dns-connections-get).

### `dns_connections.delete()`

Disconnect a DNS provider account

```python
def delete(
    id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DeletedDnsConnectionResource
```

Disconnects the account as Disconnect does in the app: the records OpenEmail wrote through it come down, every domain it serves is detached, and the connection is revoked at the provider. A verified domain whose records come down stops receiving mail, so read `get` first. `detached` counts what came down and lists the records still published, to delete by hand.

A connection that is already disconnected is removed from the list instead, once no domain and no record is left on it, and `removed` says so.

Scopes: `domains:write`.

**Parameters**

- `id` (`str`, required): A connection id from `list`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DeletedDnsConnectionResource` with `removed`, `confirmed` and `detached`.

**Example**

```python
from openemail import openemail

result = openemail.dns_connections.delete('dnsl_3f9a1c2e7b4d4e6f8a0b2c3d')
detached = result['detached']

if result['removed']:
    print('Removed from the list')
elif detached is not None:
    print(detached['detached'], 'domains detached')

    for record in detached['left']:
        print('Delete by hand:', record['type'], record['name'], record['content'])
```

**Notes**

- A sync running on one of its domains is refused with 409 `dns_busy`, and nothing is revoked. A disconnected connection that still has domains or records on it is refused with 409 `dns_connection_in_use`.
- A key or an access token limited to particular addresses or domains is refused with 422 `capability_unsupported`. An access token acting for a member also needs `workspace:manage` in their role, or it is refused with 403 `insufficient_authority`.
- An OAuth access token needs a verification code for this call, and is refused with 403 `step_up_required` until the app has verified one in the last 60 minutes. `is_step_up_required` on the error says so. An API key is never asked for a code.
- Not retried by the SDK.

Also available in: API [`DELETE /dns-connections/{id}`](https://openemail.uk/docs/api/reference/domains#delete-dns-connections-id); TypeScript [`dnsConnections.delete()`](https://openemail.uk/docs/sdk/reference/dns-connections#delete); Ruby [`dns_connections.delete`](https://openemail.uk/docs/ruby/reference/dns-connections#delete); CLI [`openemail dns-connections delete`](https://openemail.uk/docs/cli/reference/dns-connections#dns-connections-delete).