Senders & domains
Add a domain once; OneSend registers it on every provider and merges the DNS.
List domains with per-provider verification
GET /v1/domains
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
namerequired | 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.402Payment required (typepayment_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) ordomain_limit(sending domains);details.limit,details.usedanddetails.upgradeUrlsay what and where to upgrade.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
dnsConnectionId | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string | |
host | query | string | |
refresh | query | "0" | "1" | "true" | "false" |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
host | string or null | |
dnsHostConnectionId | string or null |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
dnsHostConnectionId | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
dnsHostConnectionId | string | |
planId | string | |
replace | array of object | At most 50 items. |
replace[].typerequired | string | |
replace[].namerequired | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string | |
fresh | query | "0" | "1" | "true" | "false" |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string | |
hostId | query | string | |
dnsHost | query | string | |
fresh | query | "0" | "1" | "true" | "false" |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
choicerequired | "forward" | "mailbox" | "existing" | "skip" | null | |
hostId | string or null |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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 |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
hostIdrequired | string | |
mode | "preview" | "confirm" | Default "preview". |
planId | string | |
replaceExisting | boolean | Default false. |
dnsHostConnectionId | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)