Retrieve a domain

GET

/domains/{domain_id}

curl --request GET \
  --url https://live-api.customers.ac/v1/domains/dom_d4e5f6a7-b8c9-0123-def4-567890123456 \
  --header 'Authorization: Bearer <token>'

• Production
• Sandbox — no real infrastructure is provisioned; operations complete instantly.

Returns a single domain by ID, including its nameserver assignments, health records, and current status.

Authorizations

• BearerAuth
  domains:read

Parameters

Path Parameters

domain_id

required

string format: uuid

Example

dom_d4e5f6a7-b8c9-0123-def4-567890123456

The unique identifier of the domain.

Responses

200

The requested domain.

Media typeapplication/json

object

data

required

object

id

required

Unique identifier for the domain.

string format: uuid

sender_id

required

The sender this domain belongs to.

string format: uuid

domain

required

The fully qualified domain name.

string

status

required

The current lifecycle status of a domain.

string

Allowed values: pending_nameservers awaiting_propagation connecting active failed deprovisioning deprovisioned

nameservers

The nameservers assigned to this domain by the platform. Configure these at your domain registrar to proceed with provisioning. This field is null until nameservers have been assigned (usually within a few minutes of sender creation). Poll GET /v1/senders/{id}/domains to check.

Array<string>

nullable

health

DNS health check results. null until the domain reaches active status.

object

spf

SPF record status.

string

Allowed values: pass fail missing

dkim

DKIM record status.

string

Allowed values: pass fail missing

mx

MX record status.

string

Allowed values: pass fail missing

last_checked_at

When the last health check was performed.

string | null format: date-time

mailboxes_count

Number of mailboxes on this domain.

integer

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "data": {
    "id": "dom_d4e5f6a7-b8c9-0123-def4-567890123456",
    "sender_id": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "domain": "outbound.acme.com",
    "status": "pending_nameservers",
    "nameservers": [
      "ns1.sending.ac",
      "ns2.sending.ac"
    ],
    "health": {
      "spf": "pass",
      "dkim": "pass",
      "mx": "pass",
      "last_checked_at": "2026-03-24T08:00:00Z"
    },
    "mailboxes_count": 3,
    "created_at": "2026-03-20T09:05:00Z",
    "updated_at": "2026-03-21T14:30:00Z"
  }
}

401

Authentication failed. The API key is missing or invalid.

Media typeapplication/json

object

error

required

object

code

required

A machine-readable error code.

string

Allowed values: auth.missing_key auth.invalid_key auth.insufficient_scope rate.quota_exceeded validation.required_field validation.invalid_value resource.not_found resource.already_exists resource.not_ready server.error

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Examples

No API key provided

{
  "error": {
    "code": "auth.missing_key",
    "message": "No API key was provided. Include your key in the Authorization header: Bearer sac_live_xxxxx.",
    "doc_url": "https://docs.sending.ac/errors/auth-missing-key"
  }
}

Invalid API key

{
  "error": {
    "code": "auth.invalid_key",
    "message": "The API key provided is invalid or has been revoked.",
    "doc_url": "https://docs.sending.ac/errors/auth-invalid-key"
  }
}

403

The API key does not have the required scope for this operation.

Media typeapplication/json

object

error

required

object

code

required

A machine-readable error code.

string

Allowed values: auth.missing_key auth.invalid_key auth.insufficient_scope rate.quota_exceeded validation.required_field validation.invalid_value resource.not_found resource.already_exists resource.not_ready server.error

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "auth.insufficient_scope",
    "message": "Your API key does not have the 'senders:write' scope required for this operation.",
    "doc_url": "https://docs.sending.ac/errors/auth-insufficient-scope"
  }
}

404

The requested resource does not exist.

Media typeapplication/json

object

error

required

object

code

required

A machine-readable error code.

string

Allowed values: auth.missing_key auth.invalid_key auth.insufficient_scope rate.quota_exceeded validation.required_field validation.invalid_value resource.not_found resource.already_exists resource.not_ready server.error

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "resource.not_found",
    "message": "No sender found with ID snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890.",
    "doc_url": "https://docs.sending.ac/errors/resource-not-found"
  }
}

429

You have exceeded the rate limit. Wait and retry.

Media typeapplication/json

object

error

required

object

code

required

A machine-readable error code.

string

Allowed values: auth.missing_key auth.invalid_key auth.insufficient_scope rate.quota_exceeded validation.required_field validation.invalid_value resource.not_found resource.already_exists resource.not_ready server.error

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "rate.quota_exceeded",
    "message": "Rate limit exceeded. You may make 120 requests per minute. Retry after 30 seconds.",
    "doc_url": "https://docs.sending.ac/errors/rate-quota-exceeded"
  }
}

Headers

Retry-After

integer

Example

30

Number of seconds to wait before retrying.

X-RateLimit-Limit

integer

Example

120

The maximum number of requests allowed per minute.

X-RateLimit-Remaining

integer

Example

0

The number of requests remaining in the current window.

X-RateLimit-Reset

integer

Example

1711267260

Unix timestamp when the rate limit window resets.