---
title: "Senders & domains API"
description: "Senders & domains in the OneSend API: 18 endpoints. Add a domain once; OneSend registers it on every provider and merges the DNS."
url: https://onesend.email/docs/api-reference/senders-domains/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Senders & domains

Add a domain once; OneSend registers it on every provider and merges the DNS.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## List domains with per-provider verification

GET `/v1/domains`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "domain",
    "name": string,
    "status": "pending" | "partial" | "verified" | "failed",
    "dnsProvider": string or null,
    "inbound": {
      "mode": "none" | "builtin" | "cloudflare" | "provider",
      "connectionId": string
    },
    "registrations": [{ … }],
    "dnsPlan": [{ … }],
    "ownership": {
      "status": "pending" | "verified",
      "record": { … }
    },
    "dnsHost": {
      "host": string,
      "detected": string,
      "name": string,
      "confidence": "high" | "medium" | "low" | "none",
      "nameservers": [string],
      "automatic": boolean,
      "zone": string or null,
      "override": string or null,
      "detectedAt": string,
      "connectionId": string or null
    },
    "receiving": {
      "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
      "hosts": [{ … }],
      "choice": "forward" | "mailbox" | "existing" | "skip" | null,
      "hostId": string or null,
      "checkedAt": string or null
    },
    "tracking": {
      "opens": boolean or null,
      "clicks": boolean or null,
      "customDomain": string or null,
      "customDomainStatus": "pending" | "verified" | "missing" | "mismatch" | null,
      "record": { … },
      "effective": { … }
    },
    "routing": {
      "allowedConnections": [string] or null,
      "connections": [{ … }]
    },
    "warnings": [string],
    "lastCheckedAt": string or null,
    "createdAt": string
  }],
  "nextCursor": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Add a domain once — registered on every provider

POST `/v1/domains`

Creates the domain on each connected provider through its API (a provider account that already has the domain is used as it is: no new provider domain or DKIM keys), merges every DNS requirement into one plan (single SPF with lookup check, one DKIM per provider, DMARC, inbound MX), detects the DNS host from the nameservers, optionally writes the records through a DNS host connection (`autoApplyDns`) and starts verification polling.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` | The domain you send from, for example acme.com or mail.acme.com. |
| `connections` | `array of string` | Sending providers to register the domain on. Default: every active one. |
| `dnsConnectionId` | `string` | DNS host connection (Settings > DNS hosts) that writes the DNS records for you. A Cloudflare sending provider with DNS permission also works. |
| `autoApplyDns` | `boolean` | Write the DNS records right away through `dnsConnectionId`, or through a connection for the detected DNS host. Default false. |
| `inbound` | `"none" \| "builtin" \| "cloudflare"` | Receive mail for this domain: `builtin` (this server on port 25) or `cloudflare` (Email Routing worker). Default "none". |

### Responses

`201` Success

```
{
  "id": string,
  "object": "domain",
  "name": string,
  "status": "pending" | "partial" | "verified" | "failed",
  "dnsProvider": string or null,
  "inbound": {
    "mode": "none" | "builtin" | "cloudflare" | "provider",
    "connectionId": string
  },
  "registrations": [{
    "connectionId": string,
    "provider": string,
    "status": "pending" | "verified" | "failed" | "unsupported",
    "error": string or null,
    "errorCode": string or null
  }],
  "dnsPlan": [{
    "type": "TXT" | "CNAME" | "MX" | "A",
    "name": string,
    "value": string,
    "priority": number,
    "ttl": number,
    "purpose": string,
    "providers": [string],
    "status": "pending" | "ok" | "mismatch" | "missing",
    "note": string
  }],
  "ownership": {
    "status": "pending" | "verified",
    "record": {
      "type": "TXT",
      "name": string,
      "value": string
    }
  },
  "dnsHost": {
    "host": string,
    "detected": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "override": string or null,
    "detectedAt": string,
    "connectionId": string or null
  },
  "receiving": {
    "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
    "hosts": [{
      "id": string or null,
      "name": string
    }],
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "checkedAt": string or null
  },
  "tracking": {
    "opens": boolean or null,
  …
```

**Errors: 400, 401, 402, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `402` Payment required (type `payment_required`), only on the cloud edition when cloud plans are enabled (they are off by default): the plan's limit is reached, `plan_limit` (sending providers in use) or `domain_limit` (sending domains); `details.limit`, `details.used` and `details.upgradeUrl` say what and where to upgrade.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Domains already set up in your providers

GET `/v1/domains/provider-domains`

For each connected provider whose API can list domains: the domains that already exist in that account, and whether each is in this workspace yet. Adding one of them (POST /v1/domains) uses the provider's existing entry as it is: no new provider domain, no new DKIM keys. Changes nothing.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "connectionId": string,
    "name": string,
    "provider": string,
    "providerName": string,
    "status": string,
    "supported": boolean,
    "error": string or null,
    "domains": [{ … }]
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Get a domain and its merged DNS plan

GET `/v1/domains/{id}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "domain",
  "name": string,
  "status": "pending" | "partial" | "verified" | "failed",
  "dnsProvider": string or null,
  "inbound": {
    "mode": "none" | "builtin" | "cloudflare" | "provider",
    "connectionId": string
  },
  "registrations": [{
    "connectionId": string,
    "provider": string,
    "status": "pending" | "verified" | "failed" | "unsupported",
    "error": string or null,
    "errorCode": string or null
  }],
  "dnsPlan": [{
    "type": "TXT" | "CNAME" | "MX" | "A",
    "name": string,
    "value": string,
    "priority": number,
    "ttl": number,
    "purpose": string,
    "providers": [string],
    "status": "pending" | "ok" | "mismatch" | "missing",
    "note": string
  }],
  "ownership": {
    "status": "pending" | "verified",
    "record": {
      "type": "TXT",
      "name": string,
      "value": string
    }
  },
  "dnsHost": {
    "host": string,
    "detected": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "override": string or null,
    "detectedAt": string,
    "connectionId": string or null
  },
  "receiving": {
    "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
    "hosts": [{
      "id": string or null,
      "name": string
    }],
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "checkedAt": string or null
  },
  "tracking": {
    "opens": boolean or null,
  …
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Update a domain: tracking and allowed sending providers

PATCH `/v1/domains/{id}`

`tracking`: open and click tracking for email sent from this domain (`true`, `false`, or `null` for the workspace default) and an optional custom tracking subdomain such as `links.acme.com`. Precedence: the email's own `tracking` wins, then the domain, then the workspace defaults (PATCH /v1/workspace). The custom subdomain must be under this domain; its CNAME record joins the DNS plan and tracked links use it once the record is found (until then the default tracking host is used). `allowedConnections`: the sending providers that may send for this domain (`null`: every provider where the domain is verified). The router never picks a provider where the domain is not verified, and never one outside this list. Listed providers that do not have the domain yet get it set up.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `tracking` | `object` |  |
| `tracking.opens` | `boolean or null` | Open tracking for email from this domain. null: use the workspace default. |
| `tracking.clicks` | `boolean or null` | Click tracking for email from this domain. null: use the workspace default. |
| `tracking.customDomain` | `string or null` | Tracking subdomain of this domain, for example links.acme.com. null or "" removes it. |
| `allowedConnections` | `array of string or null` | Connections allowed to send for this domain. null: automatic (every provider where the domain is verified). The domain is set up on listed providers that do not have it yet. At most 100 items. |

### Responses

`200` Success

```
{
  "id": string,
  "object": "domain",
  "name": string,
  "status": "pending" | "partial" | "verified" | "failed",
  "dnsProvider": string or null,
  "inbound": {
    "mode": "none" | "builtin" | "cloudflare" | "provider",
    "connectionId": string
  },
  "registrations": [{
    "connectionId": string,
    "provider": string,
    "status": "pending" | "verified" | "failed" | "unsupported",
    "error": string or null,
    "errorCode": string or null
  }],
  "dnsPlan": [{
    "type": "TXT" | "CNAME" | "MX" | "A",
    "name": string,
    "value": string,
    "priority": number,
    "ttl": number,
    "purpose": string,
    "providers": [string],
    "status": "pending" | "ok" | "mismatch" | "missing",
    "note": string
  }],
  "ownership": {
    "status": "pending" | "verified",
    "record": {
      "type": "TXT",
      "name": string,
      "value": string
    }
  },
  "dnsHost": {
    "host": string,
    "detected": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "override": string or null,
    "detectedAt": string,
    "connectionId": string or null
  },
  "receiving": {
    "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
    "hosts": [{
      "id": string or null,
      "name": string
    }],
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "checkedAt": string or null
  },
  "tracking": {
    "opens": boolean or null,
  …
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Remove a domain from OneSend

DELETE `/v1/domains/{id}`

Provider-side domains are left in place.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Re-check verification on every provider and DNS

POST `/v1/domains/{id}/verify`

Also registers the domain on providers connected after it was added.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "domain",
  "name": string,
  "status": "pending" | "partial" | "verified" | "failed",
  "dnsProvider": string or null,
  "inbound": {
    "mode": "none" | "builtin" | "cloudflare" | "provider",
    "connectionId": string
  },
  "registrations": [{
    "connectionId": string,
    "provider": string,
    "status": "pending" | "verified" | "failed" | "unsupported",
    "error": string or null,
    "errorCode": string or null
  }],
  "dnsPlan": [{
    "type": "TXT" | "CNAME" | "MX" | "A",
    "name": string,
    "value": string,
    "priority": number,
    "ttl": number,
    "purpose": string,
    "providers": [string],
    "status": "pending" | "ok" | "mismatch" | "missing",
    "note": string
  }],
  "ownership": {
    "status": "pending" | "verified",
    "record": {
      "type": "TXT",
      "name": string,
      "value": string
    }
  },
  "dnsHost": {
    "host": string,
    "detected": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "override": string or null,
    "detectedAt": string,
    "connectionId": string or null
  },
  "receiving": {
    "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
    "hosts": [{
      "id": string or null,
      "name": string
    }],
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "checkedAt": string or null
  },
  "tracking": {
    "opens": boolean or null,
  …
```

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Write the DNS plan through the DNS host connection

POST `/v1/domains/{id}/apply-dns`

Earlier form of POST /v1/domains/{id}/dns-apply (no plan check). Works with any DNS host connection and with a Cloudflare sending provider.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `dnsConnectionId` | `string` |  |

### Responses

`200` Success

```
{
  "results": [{
    "name": string,
    "type": string,
    "action": string,
    "error": string or null
  }],
  "domain": {
    "id": string,
    "object": "domain",
    "name": string,
    "status": "pending" | "partial" | "verified" | "failed",
    "dnsProvider": string or null,
    "inbound": {
      "mode": "none" | "builtin" | "cloudflare" | "provider",
      "connectionId": string
    },
    "registrations": [{
      "connectionId": string,
      "provider": string,
      "status": "pending" | "verified" | "failed" | "unsupported",
      "error": string or null,
      "errorCode": string or null
    }],
    "dnsPlan": [{
      "type": "TXT" | "CNAME" | "MX" | "A",
      "name": string,
      "value": string,
      "priority": number,
      "ttl": number,
      "purpose": string,
      "providers": [string],
      "status": "pending" | "ok" | "mismatch" | "missing",
      "note": string
    }],
    "ownership": {
      "status": "pending" | "verified",
      "record": {
        "type": "TXT",
        "name": string,
        "value": string
      }
    },
    "dnsHost": {
      "host": string,
      "detected": string,
      "name": string,
      "confidence": "high" | "medium" | "low" | "none",
      "nameservers": [string],
      "automatic": boolean,
      "zone": string or null,
      "override": string or null,
      "detectedAt": string,
      "connectionId": string or null
    },
    "receiving": {
      "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
      "hosts": [{ … }],
      "choice": "forward" | "mailbox" | "existing" | "skip" | null,
      "hostId": string or null,
  …
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Export the DNS plan as a BIND zone file (text/plain)

GET `/v1/domains/{id}/zone`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success (text/plain)

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## DNS setup instructions for the domain's DNS host

GET `/v1/domains/{id}/dns-setup`

The detected DNS host, its steps, and every record formatted exactly as that host's form wants it (name as `@`, relative or full; quotes; MX priority field). `host` shows the instructions for another host; `refresh=true` looks up the nameservers again.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `host` | query | `string` |  |
| `refresh` | query | `"0" \| "1" \| "true" \| "false"` |  |

### Responses

`200` Success

```
{
  "domainId": string,
  "domain": string,
  "detection": {
    "domain": string,
    "host": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "note": string or null,
    "connectionId": string or null,
    "detectedAt": string
  },
  "host": string,
  "hostName": string,
  "automatic": boolean,
  "guide": {
    "nameField": "relative" | "fqdn" | "fqdn-dot",
    "apex": string,
    "txtQuotes": "none" | "required",
    "longTxt": "whole" | "split",
    "mxPriority": "field" | "in-value",
    "ttl": string,
    "dnsPage": string,
    "steps": [string],
    "docsUrl": string or null
  },
  "connection": {
    "id": string,
    "object": "dns_host_connection",
    "host": string,
    "name": string,
    "keyHint": string or null,
    "config": map of string,
    "status": "untested" | "ok" | "error",
    "lastError": string or null,
    "lastTestedAt": string or null,
    "createdAt": string,
    "updatedAt": string
  },
  "records": [{
    "purpose": string,
    "type": string,
    "name": string,
    "value": string,
    "priority": number or null,
    "status": string or null,
    "note": string or null,
    "formatted": {
      "type": string,
      "name": string,
      "nameHint": string,
      "fqdn": string,
      "value": string,
      "priority": number or null,
      "ttl": string,
      "notes": [string]
    }
  …
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Choose the DNS host or connection for a domain

PATCH `/v1/domains/{id}/dns-host`

`host` overrides detection for the instructions (null = detected host). `dnsHostConnectionId` chooses the connection that writes records (null = none).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `host` | `string or null` |  |
| `dnsHostConnectionId` | `string or null` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "domain",
  "name": string,
  "status": "pending" | "partial" | "verified" | "failed",
  "dnsProvider": string or null,
  "inbound": {
    "mode": "none" | "builtin" | "cloudflare" | "provider",
    "connectionId": string
  },
  "registrations": [{
    "connectionId": string,
    "provider": string,
    "status": "pending" | "verified" | "failed" | "unsupported",
    "error": string or null,
    "errorCode": string or null
  }],
  "dnsPlan": [{
    "type": "TXT" | "CNAME" | "MX" | "A",
    "name": string,
    "value": string,
    "priority": number,
    "ttl": number,
    "purpose": string,
    "providers": [string],
    "status": "pending" | "ok" | "mismatch" | "missing",
    "note": string
  }],
  "ownership": {
    "status": "pending" | "verified",
    "record": {
      "type": "TXT",
      "name": string,
      "value": string
    }
  },
  "dnsHost": {
    "host": string,
    "detected": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "override": string or null,
    "detectedAt": string,
    "connectionId": string or null
  },
  "receiving": {
    "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
    "hosts": [{
      "id": string or null,
      "name": string
    }],
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "checkedAt": string or null
  },
  "tracking": {
    "opens": boolean or null,
  …
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Preview DNS changes (dry run)

POST `/v1/domains/{id}/dns-plan`

Reads the zone at the DNS host and shows, per record, whether it would be created, updated (SPF is merged into the existing record, never duplicated), left unchanged, replaced (`replace`: a DKIM key or return-path record of the provider holds another value, most likely from another account at that provider; only written when chosen on apply) or is a conflict that is not written. Changes nothing.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `dnsHostConnectionId` | `string` |  |

### Responses

`200` Success

```
{
  "domainId": string,
  "connectionId": string,
  "host": string,
  "zone": string,
  "items": [{
    "action": "create" | "update" | "unchanged" | "replace" | "conflict",
    "purpose": string,
    "type": string,
    "name": string,
    "value": string,
    "priority": number or null,
    "current": [{ … }],
    "reason": string,
    "warning": string or null
  }],
  "counts": {
    "create": number,
    "update": number,
    "unchanged": number,
    "replace": number,
    "conflict": number
  },
  "planId": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Apply DNS changes

POST `/v1/domains/{id}/dns-apply`

Writes the create and update items of the plan through the DNS host connection. Pass the `planId` from POST /dns-plan: if the zone changed in between, nothing is written (409 `plan_changed`). Conflicts are never written. `replace` items are written only when listed in `replace` (otherwise the existing record, and the setup that uses it, is kept). The response lists the previous values (and the host snapshot, where the host keeps one) so a change can be undone.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `dnsHostConnectionId` | `string` |  |
| `planId` | `string` |  |
| `replace` | `array of object` | At most 50 items. |
| `replace[].type`required | `string` |  |
| `replace[].name`required | `string` |  |

### Responses

`200` Success

```
{
  "results": [{
    "type": string,
    "name": string,
    "action": string,
    "status": "applied" | "skipped" | "failed",
    "error": string or null
  }],
  "backup": {
    "note": string or null,
    "snapshotId": string or null,
    "records": [{
      "type": string,
      "name": string,
      "value": string,
      "priority": number or null
    }]
  },
  "domain": {
    "id": string,
    "object": "domain",
    "name": string,
    "status": "pending" | "partial" | "verified" | "failed",
    "dnsProvider": string or null,
    "inbound": {
      "mode": "none" | "builtin" | "cloudflare" | "provider",
      "connectionId": string
    },
    "registrations": [{
      "connectionId": string,
      "provider": string,
      "status": "pending" | "verified" | "failed" | "unsupported",
      "error": string or null,
      "errorCode": string or null
    }],
    "dnsPlan": [{
      "type": "TXT" | "CNAME" | "MX" | "A",
      "name": string,
      "value": string,
      "priority": number,
      "ttl": number,
      "purpose": string,
      "providers": [string],
      "status": "pending" | "ok" | "mismatch" | "missing",
      "note": string
    }],
    "ownership": {
      "status": "pending" | "verified",
      "record": {
        "type": "TXT",
        "name": string,
        "value": string
      }
    },
    "dnsHost": {
      "host": string,
      "detected": string,
      "name": string,
      "confidence": "high" | "medium" | "low" | "none",
      "nameservers": [string],
  …
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Diagnose the DNS records

GET `/v1/domains/{id}/diagnostics`

Per record: found, missing, wrong value or propagating, with the likely mistake and how to fix it (domain typed twice, extra quotes, two SPF records, SPF missing an include, DKIM cut short, CNAME conflicts, MX priority, duplicate DMARC, record on the wrong name). Results are cached for a minute; `fresh=true` checks again.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `fresh` | query | `"0" \| "1" \| "true" \| "false"` |  |

### Responses

`200` Success

```
{
  "domainId": string,
  "domain": string,
  "checkedAt": string,
  "cached": boolean,
  "summary": {
    "found": number,
    "missing": number,
    "wrong_value": number,
    "propagating": number,
    "unknown": number
  },
  "records": [{
    "type": string,
    "name": string,
    "value": string,
    "priority": number or null,
    "purpose": string,
    "status": "found" | "missing" | "wrong_value" | "propagating" | "unknown",
    "found": [string],
    "problems": [{ … }]
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Receiving host catalog

GET `/v1/receiving-hosts`

Where mail to your domain can arrive. OneSend does not receive mail for you: the host your MX records point to does. `forwarding` services forward to an inbox you already have (for example Cloudflare Email Routing to Gmail); `mailbox` hosts keep the mailboxes. Each entry has the MX records, the SPF include, other records the host asks for, its setup page and whether it has a free tier. `unverified` hosts have no records here: follow `setupUrl`.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "name": string,
    "category": "forwarding" | "mailbox",
    "verification": "verified" | "unverified",
    "mx": [{ … }] or null,
    "mxSource": "fixed" | "host_console",
    "spfInclude": string or null,
    "extraRecords": [{ … }],
    "notes": [string],
    "setupUrl": string,
    "sources": [string],
    "freeTier": boolean,
    "freeTierNote": string or null,
    "requiresDnsHost": string or null,
    "applyable": boolean
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Receiving status and records for a domain

GET `/v1/domains/{id}/receiving`

Reads the domain's MX and SPF from public DNS and says where mail arrives: `ok` (one known host, SPF includes it), `no_mx` (mail bounces), `spf_missing` (MX points to a host the SPF record does not include), `mixed` (several hosts), `unknown_host` or `lookup_failed`. `recommendation` has the records for `hostId` (default: the chosen host, else the detected one), typed for the domain's DNS host (`dnsHost` for another), with one SPF record merged from what is published, the sending providers' root SPF and the host's include (nested lookups counted, limit 10). `warnings` say when an MX change would move existing mail. Results are cached for a minute; `fresh=true` checks again.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `hostId` | query | `string` |  |
| `dnsHost` | query | `string` |  |
| `fresh` | query | `"0" \| "1" \| "true" \| "false"` |  |

### Responses

`200` Success

```
{
  "domainId": string,
  "domain": string,
  "checkedAt": string,
  "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
  "nullMx": boolean,
  "mx": [{
    "host": string,
    "priority": number,
    "hostId": string or null
  }],
  "hosts": [{
    "id": string or null,
    "name": string,
    "category": "forwarding" | "mailbox" | null
  }],
  "spf": {
    "records": number,
    "record": string or null,
    "includesHost": boolean or null
  },
  "choice": {
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "updatedAt": string or null
  },
  "matchesChoice": boolean or null,
  "subdomain": boolean,
  "recommendation": {
    "hostId": string,
    "hostName": string,
    "records": [{
      "purpose": "mx" | "spf" | "other",
      "type": string,
      "name": string,
      "value": string or null,
      "priority": number or null,
      "note": string or null,
      "formatted": { … }
    }],
    "spf": {
      "value": string,
      "lookups": number,
      "overLimit": boolean,
      "changed": boolean
    },
    "copyText": string
  },
  "dnsHost": {
    "host": string,
    "name": string,
    "automatic": boolean,
    "connectionId": string or null,
    "guide": {
      "nameField": "relative" | "fqdn" | "fqdn-dot",
      "apex": string,
      "txtQuotes": "none" | "required",
      "longTxt": "whole" | "split",
      "mxPriority": "field" | "in-value",
      "ttl": string,
  …
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Choose where mail to the domain should arrive

PATCH `/v1/domains/{id}/receiving`

`forward` or `mailbox` with a `hostId` of that category, `existing` (already set up: OneSend only checks it), `skip`, or null to clear. Saves the choice only: DNS records are not changed (use POST /v1/domains/{id}/receiving/apply).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `choice`required | `"forward" \| "mailbox" \| "existing" \| "skip" \| null` |  |
| `hostId` | `string or null` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "domain",
  "name": string,
  "status": "pending" | "partial" | "verified" | "failed",
  "dnsProvider": string or null,
  "inbound": {
    "mode": "none" | "builtin" | "cloudflare" | "provider",
    "connectionId": string
  },
  "registrations": [{
    "connectionId": string,
    "provider": string,
    "status": "pending" | "verified" | "failed" | "unsupported",
    "error": string or null,
    "errorCode": string or null
  }],
  "dnsPlan": [{
    "type": "TXT" | "CNAME" | "MX" | "A",
    "name": string,
    "value": string,
    "priority": number,
    "ttl": number,
    "purpose": string,
    "providers": [string],
    "status": "pending" | "ok" | "mismatch" | "missing",
    "note": string
  }],
  "ownership": {
    "status": "pending" | "verified",
    "record": {
      "type": "TXT",
      "name": string,
      "value": string
    }
  },
  "dnsHost": {
    "host": string,
    "detected": string,
    "name": string,
    "confidence": "high" | "medium" | "low" | "none",
    "nameservers": [string],
    "automatic": boolean,
    "zone": string or null,
    "override": string or null,
    "detectedAt": string,
    "connectionId": string or null
  },
  "receiving": {
    "status": "ok" | "no_mx" | "spf_missing" | "mixed" | "unknown_host" | "lookup_failed",
    "hosts": [{
      "id": string or null,
      "name": string
    }],
    "choice": "forward" | "mailbox" | "existing" | "skip" | null,
    "hostId": string or null,
    "checkedAt": string or null
  },
  "tracking": {
    "opens": boolean or null,
  …
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Write the receiving host's MX and SPF records (preview, then confirm)

POST `/v1/domains/{id}/receiving/apply`

Through the domain's DNS host connection. `mode: preview` (the default) reads the zone and lists what would be created, updated, removed or is a conflict; nothing is written. `mode: confirm` with the preview's `planId` writes it (409 `plan_changed` when the zone changed in between). When mail arrives at another host now, its MX records are only removed with `replaceExisting: true` (otherwise 409 `mx_in_use`); old and new MX records are never left side by side. SPF is merged into the one existing record. Needs the admin role; test-mode keys are refused.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `hostId`required | `string` |  |
| `mode` | `"preview" \| "confirm"` | Default "preview". |
| `planId` | `string` |  |
| `replaceExisting` | `boolean` | Default false. |
| `dnsHostConnectionId` | `string` |  |

### Responses

`200` Success

```
{
  "mode": "preview" | "confirm",
  "domainId": string,
  "hostId": string,
  "connectionId": string,
  "dnsHost": string,
  "zone": string,
  "planId": string,
  "items": [{
    "action": "create" | "update" | "unchanged" | "conflict" | "remove",
    "purpose": "mx" | "spf",
    "type": string,
    "name": string,
    "value": string,
    "priority": number or null,
    "current": [{ … }],
    "reason": string,
    "warning": string or null
  }],
  "counts": {
    "create": number,
    "update": number,
    "unchanged": number,
    "conflict": number,
    "remove": number
  },
  "existingMx": [{
    "type": string,
    "name": string,
    "value": string,
    "priority": number or null
  }],
  "needsReplaceConfirmation": boolean,
  "warnings": [{
    "code": string,
    "message": string,
    "params": map of string
  }],
  "results": [{
    "type": string,
    "name": string,
    "value": string,
    "action": string,
    "status": "applied" | "skipped" | "failed",
    "error": string or null
  }] or null,
  "backup": {
    "note": string or null,
    "snapshotId": string or null,
    "records": [{
      "type": string,
      "name": string,
      "value": string,
      "priority": number or null
    }]
  }
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
