Managing domains

The Manage Domains API is in beta. The API and features may change before general availability.

The Manage Domains API lets you programmatically register and verify custom email domains for use with Transactional Send and Nylas Inbound. You can also manage domains through the Nylas Dashboard.

Before you begin

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

• A Nylas Service Account for authenticating requests. Contact Nylas Support to get your credentials file.
• A contract with Nylas that includes domain management capabilities.

All Manage Domains API requests use Nylas Service Account authentication, 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.

RequestResponse (JSON)

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

{
  "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.

RequestResponse (JSON)

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

{
  "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."
  }
}

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.

Trigger verification

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

RequestResponse (JSON)

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

{
  "request_id": "3b9de505-957c-4962-a119-38f98934e55e",
  "data": {
    "status": "done",
    "message": "Domain already verified of type 'ownership'."
  }
}

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	A TXT record that verifies the DKIM public key for authenticating outgoing mail.
spf	Transactional Send	A TXT record that authorizes Nylas to send email on your behalf.
feedback	Transactional Send	An MX record that enables bounce detection and feedback loop reporting.
mx	Nylas Inbound	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 Inbound, verify: ownership and mx.

List domains

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

Request

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.

Request

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.

Request

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

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.

Request

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"

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

Related resources

• Nylas Service Account authentication — how to authenticate Manage Domains API requests
• Transactional Send quickstart — send email from a verified domain
• Nylas Inbound quickstart — receive email at a verified domain
• Email domain warm up — build sender reputation for a new domain
• Manage Domains API reference — full API reference for all domain endpoints