---
search:
  tags:
    - Domains
    - POST
seo:
  description: >-
    Create a domain. Reference for the POST /domains endpoint in the BillionSend
    API.
sidebar:
  label: Create a domain
  badge: POST
title: Create a domain
type: openapi-operation
---
`POST /domains`

**Request body** (`application/json`, required)

- `name` (string, required)
- `region` (string) — SES region of the identity, one of the regions this deployment serves (the values listed here; the first is the default). Any other region is rejected with 422. A domain has one region, fixed when it is added.
- `custom_return_path` (string)
- `open_tracking` (boolean) — Inject a tracking pixel served from the tracking host and record email.opened events. Off by default.
- `click_tracking` (boolean) — Rewrite links to redirect through the tracking host and record email.clicked events. Off by default.
- `tracking_subdomain` (string) — DNS label of the domain's own tracking host, e.g. "links" for links.\<domain\>. Optional: without one, tracked links use the shared tracking host. Setting it adds a Tracking CNAME to records\[\] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Tracking record then reads verified, and links go through it from then on. A subdomain that does not activate within 72 hours reads failed; send the same tracking\_subdomain again to retry.
- `unsubscribe_subdomain` (string) — BillionSend extension: DNS label of the domain's own unsubscribe host, e.g. "unsubscribe" for unsubscribe.\<domain\>. Optional: without one, unsubscribe links (and the List-Unsubscribe header) use the shared unsubscribe host. Setting it adds an Unsubscribe CNAME to records\[\] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Unsubscribe record then reads verified, and unsubscribe links go through it from then on. The same label as tracking\_subdomain is allowed: one host then serves both and records\[\] shows one row. A subdomain that does not activate within 72 hours reads failed; send the same unsubscribe\_subdomain again to retry. Kept apart from tracking\_subdomain because ad blockers filter tracking hosts by name.
- `capabilities` (object) — What the domain is used for (sending, receiving); omitted fields keep their value.

Request body example:

```json
{
  "name": "string",
  "region": "us-east-1",
  "custom_return_path": "send",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "string",
  "unsubscribe_subdomain": "string",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  }
}
```

**Responses**

- `200` — Domain created
- `401` — Missing, malformed, unknown or revoked API key
- `403` — Plan domain limit reached, an own tracking or unsubscribe subdomain needs a paid plan, or the key is held to one domain (it cannot create domains)
- `409` — Domain already added
- `422` — Validation error
- `429` — Too many domains created recently, or the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "status": "string",
  "created_at": "string",
  "region": "string",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "string",
  "tracking_status": "pending",
  "tracking_error": "string",
  "unsubscribe_subdomain": "string",
  "unsubscribe_status": "pending",
  "unsubscribe_error": "string",
  "unsubscribe_page": {
    "brand_name": "string",
    "message": "string",
    "success_message": "string",
    "redirect_url": "string",
    "background_color": "string",
    "text_color": "string",
    "accent_color": "string",
    "logo_radius": "square",
    "logo_url": "string"
  },
  "capabilities": {
    "sending": "string",
    "receiving": "string"
  },
  "receiving_catch_all": true,
  "shared": true,
  "sending_mode": "open",
  "sending_mode_reason": "plan",
  "records": [
    {
      "record": "string",
      "name": "string",
      "type": "string",
      "ttl": "string",
      "status": "string",
      "value": "string",
      "priority": 0,
      "live": "found",
      "detail": "string",
      "inherited_from": "string",
      "policy": "none"
    }
  ]
}
```
