API · Domains

Create Domain

Add a domain for sending or receiving email (requires full access). Setup runs asynchronously; receiving requires a supported region.

POST/domainsFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`name` body · required	`string`	The name of the domain you want to create.
`region` body · optional	`"us-east-1" \| "eu-west-1" \| "sa-east-1" \| "ap-northeast-1" \| null`	Sending region, defaulting to your installation’s region or us-east-1 when none is configured.
`custom_return_path` body · optional	`string \| null`	Return-Path subdomain for SPF and bounce handling, defaulting to send.
`open_tracking` body · optional	`boolean \| null`	Enable open tracking over HTTP; HTTPS tracking requires a CDN and certificate configured by your operator.
`click_tracking` body · optional	`boolean \| null`	Enable click tracking over HTTP; HTTPS tracking requires a CDN and certificate configured by your operator.
`tracking_subdomain` body · optional	`string \| null`	Tracking subdomain activated after CNAME verification, which can be changed but cannot be removed.
`tls` body · optional	`"opportunistic" \| "enforced" \| null`	See operation behavior.
`capabilities` body · optional	`object`	Sending and receiving settings; receiving requires a region that supports inbound email.
`capabilities.sending` body · optional	`"enabled" \| "disabled" \| null`	See operation behavior.
`capabilities.receiving` body · optional	`"enabled" \| "disabled" \| null`	See operation behavior.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/domains" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example.com","region":"us-east-1"}'

Response

201 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "id": "YOUR_ID",
  "name": "example",
  "status": "pending",
  "created_at": "example",
  "region": "us-east-1",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": "example",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "tls": "opportunistic",
  "records": [
    {
      "record": "SPF",
      "name": "example",
      "type": "MX",
      "ttl": "example",
      "status": "pending",
      "value": "example",
      "priority": 0
    }
  ]
}

Behavior and errors

Create accepts TLS and sending/receiving capabilities. Your SES region and IAM policy must support the requested capabilities. DNS records can be empty while AWS setup is pending. custom_return_path cannot be changed later. A name registered by another team on the installation returns 403 validation_error; claim the domain if you own it. The response status is 201.

Use a full-access credential. Resource IDs belong to your team; an unknown or foreign resource returns 404. See authentication, errors, rate limits, and compatibility for the shared contract.