# Create a domain

> Adds a sending domain and returns it with the DNS records to publish.

Source: https://docs.pidgely.com/api-reference/v1/domains/create/

`POST https://api.pidgely.com/v1/domains`

Adds a sending domain and returns it with the DNS records to publish.

**Authorization:** `Bearer pdg_…`. An API key with the `full` scope.

## Body parameters

JSON object.

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Display name. |
| `region` | string | No | Informative; set by the platform. |
| `custom_return_path` | string | No | Bounce subdomain label (default `bounces`). |
| `tls` | string | No | `opportunistic` (default): TLS when the receiving server offers it. `enforced`: deliver only over TLS. One of `opportunistic`, `enforced`. |
| `open_tracking` | boolean | No | Accepted, not supported yet (always false). |
| `click_tracking` | boolean | No | Accepted, not supported yet. |
| `capabilities` | object | No | — |
| `capabilities.sending` | string | No | — |
| `capabilities.receiving` | string | No | `enabled` is rejected (receiving not supported yet). |

## Request

```bash tab="cURL"
curl -X POST 'https://api.pidgely.com/v1/domains' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "acme.com"
}'
```

## Response

`201 Created` with a JSON object.

## Errors

Native routes return `{"error": {"code", "message", "field", "request_id"}}`. See [Errors](https://docs.pidgely.com/errors/#native-api-errors).

| Status | Code | When |
|---|---|---|
| 401 | `missing_api_key` | No `Authorization: Bearer` header. |
| 403 | `invalid_api_key`, `insufficient_scope` | The key is invalid or lacks the scope. |
| 404 | `not_found` | The resource does not exist in this account. |
| 422 | `validation_error` | A field is missing or invalid; `field` names it. |
| 429 | `rate_limited`, `daily_quota_exceeded` | Too many requests, or the quota is used up. |