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 and errors are described in the overview.

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.

FieldTypeDescription
namerequiredstringThe domain you send from, for example acme.com or mail.acme.com.
connectionsarray of stringSending providers to register the domain on. Default: every active one.
dnsConnectionIdstringDNS host connection (Settings > DNS hosts) that writes the DNS records for you. A Cloudflare sending provider with DNS permission also works.
autoApplyDnsbooleanWrite 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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
trackingobject
tracking.opensboolean or nullOpen tracking for email from this domain. null: use the workspace default.
tracking.clicksboolean or nullClick tracking for email from this domain. null: use the workspace default.
tracking.customDomainstring or nullTracking subdomain of this domain, for example links.acme.com. null or "" removes it.
allowedConnectionsarray of string or nullConnections 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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
dnsConnectionIdstring

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

NameInTypeDescription
idrequiredpathstring

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

NameInTypeDescription
idrequiredpathstring
hostquerystring
refreshquery"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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
hoststring or null
dnsHostConnectionIdstring 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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
dnsHostConnectionIdstring

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
dnsHostConnectionIdstring
planIdstring
replacearray of objectAt most 50 items.
replace[].typerequiredstring
replace[].namerequiredstring

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

NameInTypeDescription
idrequiredpathstring
freshquery"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

NameInTypeDescription
idrequiredpathstring
hostIdquerystring
dnsHostquerystring
freshquery"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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
choicerequired"forward" | "mailbox" | "existing" | "skip" | null
hostIdstring 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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
hostIdrequiredstring
mode"preview" | "confirm"Default "preview".
planIdstring
replaceExistingbooleanDefault false.
dnsHostConnectionIdstring

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)