# Create a custom domain

`POST /api/domains`

The authenticated account can create a domain. Domain names normalize to DNS form. Domains reserved for Wildmail service use cannot be added. Configure returned TXT and MX records before verification.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `domains:write`.

Audience: management.

## Request body

Required.

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "endpointId": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "domain"
  ]
}
```

Example:

```json
{
  "domain": "in.example.com",
  "endpointId": "11111111-1111-4111-8111-111111111111"
}
```

## Responses

### 201

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "domain": {
      "$ref": "#/components/schemas/Domain"
    }
  },
  "required": [
    "domain"
  ]
}
```

### 400

Invalid request.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 404

Resource not found in this account.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 409

Already claimed or domain_limit_reached. Quota errors include the limit.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503



## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/Domain

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "domain": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "mxStatus": {
      "type": "string"
    },
    "billingSuspended": {
      "type": "boolean"
    },
    "ready": {
      "type": "boolean",
      "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route."
    },
    "endpointId": {
      "type": [
        "string",
        "null"
      ]
    },
    "endpointName": {
      "type": [
        "string",
        "null"
      ]
    },
    "endpointStatus": {
      "type": [
        "string",
        "null"
      ]
    },
    "ownershipVerifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "lastOwnershipCheckAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "mxRecords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mxCheckedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "dns": {
      "type": "object",
      "properties": {
        "txtHost": {
          "type": "string"
        },
        "txtValue": {
          "type": "string"
        },
        "mxHost": {
          "type": "string"
        },
        "mxPriority": {
          "type": "integer"
        }
      },
      "required": [
        "txtHost",
        "txtValue",
        "mxHost",
        "mxPriority"
      ]
    }
  },
  "required": [
    "id",
    "domain",
    "status",
    "mxStatus",
    "billingSuspended",
    "ready",
    "endpointId",
    "endpointName",
    "endpointStatus",
    "ownershipVerifiedAt",
    "lastOwnershipCheckAt",
    "mxRecords",
    "mxCheckedAt",
    "createdAt",
    "updatedAt",
    "dns"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```
