Add a mailbox domain

curl --request POST \
  --url https://app.sendmux.ai/api/v1/domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "mail.acme.com"
}
'

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "id": "mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
    "domain": "mail.acme.com",
    "ses_dkim_status": "<string>",
    "verified_at": "<string>",
    "created_at": "<string>",
    "mailbox_count": 14,
    "dns_records": {
      "mx": [
        {
          "priority": 10,
          "target": "mail.sendmux.ai"
        }
      ],
      "spf": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      },
      "dmarc": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      },
      "dkim": [
        {
          "name": "_sendmux.acme.com",
          "value": "sendmux-verify=team_abc123"
        }
      ],
      "verification": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      }
    }
  }
}

Domains

Add a mailbox domain

Creates a new sending domain and returns the DNS records the customer must place before verification can succeed. Provisioning touches both our mail platform and Amazon SES — on any failure the partial state is automatically rolled back.

Supply an Idempotency-Key header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return 409 idempotency_conflict.

POST

/

domains

Add a mailbox domain

curl --request POST \
  --url https://app.sendmux.ai/api/v1/domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "mail.acme.com"
}
'

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "id": "mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
    "domain": "mail.acme.com",
    "ses_dkim_status": "<string>",
    "verified_at": "<string>",
    "created_at": "<string>",
    "mailbox_count": 14,
    "dns_records": {
      "mx": [
        {
          "priority": 10,
          "target": "mail.sendmux.ai"
        }
      ],
      "spf": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      },
      "dmarc": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      },
      "dkim": [
        {
          "name": "_sendmux.acme.com",
          "value": "sendmux-verify=team_abc123"
        }
      ],
      "verification": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      }
    }
  }
}

Authorizations

Authorization

string

header

required

Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys.

Headers

Idempotency-Key

string

Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.

Maximum string length: 255

Example:

"domains-create-20260424-001"

Body

application/json

domain

string

required

Fully qualified domain name. Must be lowercased and domain-only (no scheme).

Example:

"mail.acme.com"

Response

Domain created. The response carries a Location header pointing at the canonical GET URL for the new domain.

ok

enum<boolean>

required

Available options:

true

meta

object

required

Hide child attributes

meta.request_id

string

required

Example:

"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data

object

required

Hide child attributes

data.id

string

required

Public ID

Example:

"mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data.domain

string

required

Fully qualified domain name

Example:

"mail.acme.com"

data.verification_status

enum<string>

required

Current verification state

Available options:

pending,

verified,

failed

data.ses_dkim_status

string | null

required

SES DKIM status (pending/success/failed/temporary_failure/not_started)

data.verified_at

string | null

required

ISO 8601 timestamp of last successful verification

data.created_at

string

required

ISO 8601 creation timestamp

data.mailbox_count

integer

required

Active mailboxes currently using this domain

Required range: x >= 0

Example:

14

data.dns_records

object

required

Hide child attributes

data.dns_records.mx

object[]

required

MX records the customer must place. All point at Sendmux's inbound mail servers.

Hide child attributes

data.dns_records.mx.priority

integer

required

Example:

10

data.dns_records.mx.target

string

required

Example:

"mail.sendmux.ai"

data.dns_records.spf

object

required

SPF TXT record covering both SES and Sendmux includes

Hide child attributes

data.dns_records.spf.name

string

required

Example:

"_sendmux.acme.com"

data.dns_records.spf.value

string

required

Example:

"sendmux-verify=team_abc123"

data.dns_records.dmarc

object

required

DMARC enforcement record (quarantine, no reporting)

Hide child attributes

data.dns_records.dmarc.name

string

required

Example:

"_sendmux.acme.com"

data.dns_records.dmarc.value

string

required

Example:

"sendmux-verify=team_abc123"

data.dns_records.dkim

object[]

required

Three SES DKIM CNAME records

Hide child attributes

data.dns_records.dkim.name

string

required

Example:

"_sendmux.acme.com"

data.dns_records.dkim.value

string

required

Example:

"sendmux-verify=team_abc123"

data.dns_records.verification

object

required

Ownership-proof TXT record (Sendmux-specific)

Hide child attributes

data.dns_records.verification.name

string

required

Example:

"_sendmux.acme.com"

data.dns_records.verification.value

string

required

Example:

"sendmux-verify=team_abc123"

List mailbox domains

Get a mailbox domain