# Managing domains

Source: https://developer.nylas.com/docs/v3/email/domains/

The Manage Domains API lets you programmatically register and verify custom email domains for use with [Transactional Send](/docs/v3/getting-started/transactional-send/) and [Nylas Agent Accounts](/docs/v3/agent-accounts/). You can also manage domains through the [Nylas Dashboard](https://dashboard-v3.nylas.com/organization/domains).

## Before you begin

Before you can use the Manage Domains API, you need:

- A [Nylas Service Account](/docs/v3/auth/nylas-service-account/) for authenticating requests. Contact [Nylas Support](mailto:support@nylas.com) to get your credentials file.
- A contract with Nylas that includes domain management capabilities.

All Manage Domains API requests use [Nylas Service Account authentication](/docs/v3/auth/nylas-service-account/), which requires cryptographic request signing with four custom headers (`X-Nylas-Kid`, `X-Nylas-Timestamp`, `X-Nylas-Nonce`, `X-Nylas-Signature`).

## Register a domain

To register a domain, make a `POST /v3/admin/domains` request with the domain name and address.

It's recommended to use a subdomain like `mail.example.com` or `notifications.example.com` for transactional sending. This keeps your transactional email separate from your main domain and makes DNS management easier.

```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"
  }'

```

```json [createDomain-Response (JSON)]
{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "id": "abc-123-domain-id",
    "name": "My transactional domain",
    "branded": false,
    "domain_address": "mail.example.com",
    "organization_id": "org-123",
    "region": "us",
    "verified_ownership": false,
    "verified_dkim": false,
    "verified_spf": false,
    "verified_mx": false,
    "verified_feedback": false,
    "verified_dmarc": false,
    "verified_arc": false,
    "created_at": 1742932766,
    "updated_at": 1742932766
  }
}
```

## Verify domain DNS records

After registering a domain, you must verify its DNS records before you can use it. The verification process has three steps:

1. Call the **Get domain info** endpoint to retrieve the DNS records you need to add.
2. Add the DNS records at your DNS provider.
3. Call the **Verify domain** endpoint to trigger Nylas' verification check.

### Get DNS record info

Call `POST /v3/admin/domains/{domain_id}/info` with the verification `type` to get the DNS records you need to configure. For a type that's already verified, the response returns `status: "done"` and, where the records can be reconstructed, includes the configured records so you can display or export them after verification completes.

```bash
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/info" \
  -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 '{
    "type": "ownership"
  }'

```

```json [getDomainInfo-Response (JSON)]
{
  "request_id": "48884700-1032-4fc4-80ab-db2d8d763f26",
  "data": {
    "domain_id": "70124d7c-c3e3-44ac-902b-00f53c2d8014",
    "attempt": {
      "type": "ownership",
      "options": {
        "host": "@",
        "type": "TXT",
        "value": "nylas-ownership-verify=gNIeZAtY1lPUEpWOhA2XBB..."
      }
    },
    "status": "pending",
    "created_at": 1770242496,
    "expires_at": 1770415296,
    "message": "Please configure the TXT record for the domain to the returned options. Once done, you can retry the verification."
  }
}
```

> **Warn:** 
> **Some DNS record values are temporary and expire.** Always call the `/info` endpoint to get fresh values before configuring DNS records. If a record has expired, calling `/info` again returns updated values.

> **Info:** 
> **DKIM key size.** Nylas generates 1024-bit DKIM keys by default, which fit in a single DNS TXT record at every provider. To use a 2048-bit key instead, pass `"options": { "use_2048_bit_key": true }` in the `/info` request for `"type": "dkim"`. Some DNS providers require splitting the longer 2048-bit value across multiple TXT strings.

### Trigger verification

After you add the DNS records at your provider, call `POST /v3/admin/domains/{domain_id}/verify` to trigger the verification check.

```bash
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/verify" \
  -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 '{
    "type": "dkim"
  }'

```

```json [verifyDomain-Response (JSON)]
{
  "request_id": "3b9de505-957c-4962-a119-38f98934e55e",
  "data": {
    "status": "done",
    "message": "Domain already verified of type 'ownership'."
  }
}
```

> **Info:** 
> **Configure DNS records before calling `/verify`.** It is recommended to first configure the DNS settings and then make the first call to the `/verify` endpoint to avoid DNS caching issues. If verification fails and your configuration is correct, wait up to 24 hours (usually resolved within minutes, depending on TTL).

### Verification types

Different verification types are required depending on how you plan to use the domain.

| Type        | Required for                       | Description                                                                               |
| ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `ownership` | All domains                        | A TXT record that proves you control the domain. Required before any other verifications. |
| `dkim`      | Transactional Send, Agent Accounts | A TXT record that verifies the DKIM public key for authenticating outgoing mail.          |
| `spf`       | Transactional Send, Agent Accounts | A TXT record that authorizes Nylas to send email on your behalf.                          |
| `feedback`  | Transactional Send, Agent Accounts | An MX record that enables bounce detection and feedback loop reporting.                   |
| `mx`        | Agent Accounts                     | An MX record that routes incoming mail to Nylas.                                          |

Nylas also tracks `dmarc` and `arc` verification, but does not currently enforce them. Setting up DMARC and ARC records is recommended for better deliverability.

**For Transactional Send**, verify: `ownership`, `dkim`, `spf`, and `feedback`.

**For Nylas Agent Accounts**, verify: `ownership`, `dkim`, `spf`, `feedback`, and `mx`.

## List domains

To list all domains registered to your organization, make a `GET /v3/admin/domains` request.

```bash
curl -X GET "https://api.us.nylas.com/v3/admin/domains" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766"

```

The response includes cursor-based pagination. If the response includes a `next_cursor` value, pass it as the `page_token` query parameter to retrieve the next page.

## Get a domain

To get a specific domain, make a `GET /v3/admin/domains/{domain_id}` request.

```bash
curl -X GET "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766"

```

## Update a domain

To update a domain's name, make a `PUT /v3/admin/domains/{domain_id}` request.

```bash
curl -X PUT "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>" \
  -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": "Updated domain name"
  }'

```

> **Info:** 
> **Only the `name` field can be updated.** The `domain_address` cannot be changed after the domain is created. To use a different domain address, delete the domain and create a new one.

## Delete a domain

To delete a domain, make a `DELETE /v3/admin/domains/{domain_id}` request.

```bash
curl -X DELETE "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766"

```

> **Warn:** 
> **Deleting a domain is irreversible.** Any inboxes or sending configurations that use this domain stop working immediately.

## Related resources

- [Nylas Service Account authentication](/docs/v3/auth/nylas-service-account/) — how to authenticate Manage Domains API requests
- [Transactional Send quickstart](/docs/v3/getting-started/transactional-send/) — send email from a verified domain
- [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) — create a Nylas-hosted mailbox that receives email at a verified domain
- [Email domain warm up](/docs/v3/agent-accounts/domain-warming/) — build sender reputation for a new domain
- [Manage Domains API reference](/docs/reference/api/manage-domains/) — full API reference for all domain endpoints