Domains

Add a mailbox domain

Changed on

Creates a new domain and returns the DNS records the customer must place before verification can succeed. send_only configures outbound sending without changing MX records. send_receive also configures the domain for hosted mailboxes. Provisioning touches our email 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

Request

  • Base URL: https://app.sendmux.ai/api/v1
  • URL: https://app.sendmux.ai/api/v1/domains
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.sendmux.ai/oauth/authorize, token URL https://app.sendmux.ai/oauth/token, scopes: domain.create)

Headers

Idempotency-Keystring

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.

Example:domains-create-20260424-001

Request body

domainstring required

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

mode'send_only' | 'send_receive'

Domain usage mode. Defaults to send_receive when omitted.

Example request

{
  "domain": "mail.acme.com",
  "mode": "send_only"
}

Response

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

oktrue required

Example response

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "dns_records": {
      "dkim": [
        {
          "name": "_sendmux.acme.com",
          "value": "sendmux-verify=team_abc123"
        }
      ],
      "dmarc": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      },
      "mail_from": {
        "mx": {
          "name": "bounce.acme.com",
          "priority": 10,
          "target": "feedback-smtp.eu-central-1.amazonses.com"
        },
        "spf": {
          "name": "_sendmux.acme.com",
          "value": "sendmux-verify=team_abc123"
        }
      },
      "mx": [
        {
          "priority": 10,
          "target": "mail.sendmux.ai"
        }
      ],
      "spf": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      },
      "verification": {
        "name": "_sendmux.acme.com",
        "value": "sendmux-verify=team_abc123"
      }
    },
    "domain": "mail.acme.com",
    "id": "mdom_clxxxxxxxxxxxxxxxxxxxxxxxxx",
    "mailbox_count": 14,
    "mode": "send_receive"
  }
}

Changes

  • 7807ce923952Revision changes
    • info

      the endpoint scheme security oauth2 was added to the API

  • a53e49562216Revision changes
    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status