# Create domain

> **POST** `https://api.us.nylas.com/v3/admin/domains`

Source: https://developer.nylas.com/docs/reference/api/manage-domains/create-domain/

<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>

Registers a new email domain for your organization. After creating a domain, you must
[verify its DNS records](/docs/v3/email/domains/) before you can use it with Transactional Send or Nylas Agent Accounts.

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Nylas-Signature` | string | Yes | A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed string of the path, method, timestamp, nonce, and payload. |
| `X-Nylas-Kid` | string | Yes | The `private_key_id` from your Service Account JSON file. |
| `X-Nylas-Nonce` | string | Yes | A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a nonce, Nylas rejects the request. |
| `X-Nylas-Timestamp` | number | Yes | The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within a 5-minute window of your real request time. |

## Request body

Content-Type: application/json

- `name` (string) **(required)** - A human-readable label for the domain.
- `domain_address` (string) **(required)** - The domain address to register (for example, `mail.example.com`).

## Responses

### 200 - OK

- `request_id` (string) - ID of the request.
- `data` (object)
  - `id` (string) - Globally unique identifier for the domain.
  - `name` (string) - A human-readable label for the domain.
  - `branded` (boolean) - If `true`, this is a Nylas-branded `nylas.email` subdomain managed by Nylas. You can only have one free Nylas branded domain per organization and region. If `false`, this is a custom domain.
  - `domain_address` (string) - The domain address (for example, `mail.example.com`).
  - `organization_id` (string) - The ID of the Nylas organization that owns the domain.
  - `region` (string) - The Nylas data center region where the domain is registered.
  - `verified_ownership` (boolean) - If `true`, the domain's ownership TXT record has been verified.
  - `verified_dkim` (boolean) - If `true`, the domain's DKIM TXT record has been verified.
  - `verified_spf` (boolean) - If `true`, the domain's SPF record has been verified.
  - `verified_mx` (boolean) - If `true`, the domain's MX record has been verified.
  - `verified_feedback` (boolean) - If `true`, the domain's feedback MX record for bounce detection has been verified.
  - `verified_dmarc` (boolean) - Currently not verified by Nylas. However, it is highly recommended to set DMARC to your desired value to prevent emails going to spam.
  - `verified_arc` (boolean) - Currently not verified by Nylas.
  - `created_at` (number) - When the domain was created, in seconds using the Unix timestamp format.
  - `updated_at` (number) - When the domain was last updated, in seconds using the Unix timestamp format.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl -X POST "https://api.us.nylas.com/v3/admin/domains" \
  -H "Content-Type: application/json" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766" \
  -d '{
    "name": "My transactional domain",
    "domain_address": "mail.example.com"
  }'
```

### Python SDK

```python
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

signer = ServiceAccountSigner(
    private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
    private_key_id="<SERVICE_ACCOUNT_ID>",
)

domain = nylas.domains.create(
    request_body={
        "name": "My transactional domain",
        "domain_address": "mail.example.com",
    },
    signer=signer,
)

print(domain)

```