The Manage Domains API registers and verifies the domains you use with Transactional Send and Nylas Agent Accounts. Use it to add domains from your own code, for example when your customers bring their own sending domain. To add a domain by hand, use the Dashboard instead.
How domain registration and verification works
Section titled “How domain registration and verification works”Domains belong to your Nylas organization, so one domain works across all of your applications. You register a domain with one request, then verify it one record type at a time. Transactional Send needs 4 verified types and Agent Accounts needs 5.
Register and verify a domain with the API
failed can be retried until it returns done.Diagram as text
- Dashboard: Create an IAM API key: A principal with an Organization binding and the Domains permissions.
- Your backend: Register the domain:
POST /v3/domainsreturns the domain ID. Everyverified_*field starts asfalse. - Your backend: Get the DNS records:
POST /once per type. Values expire after 2 days.v3/ domains/ {domain_id}/ info - Your DNS provider: Add the records: TXT and MX records. Hosts are relative to the root domain's zone.
- Your backend: Verify each type:
POST /once per type.v3/ domains/ {domain_id}/ verify - status: failed → Not confirmed yet: Wait a few minutes and call
/verifyagain.
- status: failed → Not confirmed yet: Wait a few minutes and call
- Your app: Send or receive mail: Use the domain with Transactional Send or Agent Accounts. (status: done)
Before you begin
Section titled “Before you begin”You need:
- A Nylas plan that includes domain management.
- Admin access to your organization in the Nylas Dashboard.
- Access to the DNS settings for the domain you want to register.
Create an IAM API key for domains
Section titled “Create an IAM API key for domains”The Manage Domains API only accepts IAM API keys. Application API keys and access tokens don’t work. The key’s principal needs an Organization resource binding and all 4 Domains permissions. No system role includes these permissions, so you add them as direct permissions.
-
In the Dashboard, go to Nylas IAM and select Create principal. Give the principal a name that describes the service that will use it.

-
Select Next and choose Organization as the resource binding.

-
Select Next. Under Direct permissions, expand Domains, select all 4 permissions, and select Create principal.

-
Select Set up credential. Name the key, choose when it expires, and select Create.

-
Copy the key and store it securely. The Dashboard only shows it once.

Send the key in the Authorization header as a bearer token, the same way you send an application API key. To create principals and keys from code, see Manage IAM principals with the API, or use the Create IAM principal and Create IAM credential endpoints.

Register a domain
Section titled “Register a domain”Make a POST /v3/domains request with a name and the domain address. We recommend a subdomain such as mail.example.com, so your sending reputation stays separate from your main domain.
curl --request POST \ --url "https://api.us.nylas.com/v3/domains" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "Transactional mail", "domain_address": "mail.example.com" }'{ "request_id": "582538585-ff20ff48-7cf7-4e8a-acf3-bc1104f87748", "data": { "id": "0a2171c6-c298-4671-8b82-d832a7fd5170", "name": "Transactional mail", "domain_address": "mail.example.com", "organization_id": "465340d4-0000-4041-91d8-000000000000", "branded": false, "region": "us", "disabled": false, "verified_ownership": false, "verified_mx": false, "verified_spf": false, "verified_feedback": false, "verified_dkim": false, "verified_dmarc": false, "verified_arc": false, "created_at": 1794254560, "updated_at": 1794254560 }}New domains start unverified.
Verify domain DNS records
Section titled “Verify domain DNS records”Before a domain can send or receive mail, you need to verify its DNS records. For each verification type, get the record from Nylas, add it at your DNS provider, and ask Nylas to check it.
| Type | Required for | Record |
|---|---|---|
ownership | All domains | TXT record that proves you own the domain. |
dkim | Transactional Send, Agent Accounts | TXT record for DKIM signing. |
spf | Transactional Send, Agent Accounts | TXT record that authorizes Nylas to send. |
feedback | Transactional Send, Agent Accounts | MX record for bounce reports. |
mx | Agent Accounts | MX record that routes incoming mail. |
Nylas doesn’t check DMARC or ARC records, but we recommend publishing a DMARC record to improve deliverability.
Get the DNS records to add
Section titled “Get the DNS records to add”Make a POST /v3/domains/{domain_id}/info request for each verification type. The response includes the record’s host, type, and value. You can use the domain address in place of the domain ID.
curl --request POST \ --url "https://api.us.nylas.com/v3/domains/${DOMAIN_ID}/info" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY" \ --header "Content-Type: application/json" \ --data '{ "type": "ownership" }'{ "request_id": "216397503-ea08c1de-34f9-485c-971b-61cef4437eba", "data": { "domain_id": "0a2171c6-c298-4671-8b82-d832a7fd5170", "attempt": { "type": "ownership", "options": { "host": "@", "type": "TXT", "value": "nylas-ownership-verify=OSqJ8c86wi6X7HmgCB7ASOlN6Ze86oRIbRYGV7KxHR3x..." } }, "status": "pending", "created_at": 1794254567, "expires_at": 1794427367, "message": "Please configure the TXT record for the domain to the returned options. Once done, you can retry the verification." }}Record values expire after 2 days. If they expire before you verify the domain, request them again.
Add the records at your DNS provider
Section titled “Add the records at your DNS provider”Record hosts are relative to your root domain, and @ is the root domain itself. For example.com, the records look like this:
| Type | Record | Host | Value |
|---|---|---|---|
ownership | TXT | @ | Unique to your domain |
mx | MX | @ | mx.us.nylas.email |
spf | TXT | send | v=spf1 include:amazonses.com ~all |
dkim | TXT | nylas._domainkey | Unique to your domain |
feedback | MX | send | feedback-smtp.us-west-2.amazonses.com |
For a subdomain, the hosts include the subdomain. For mail.example.com, the DKIM host is nylas._domainkey.mail. Always copy the values from your own responses.
The MX record sends all incoming mail for the domain to Nylas. If the domain already receives mail somewhere else, use a separate subdomain.
Verify each record
Section titled “Verify each record”Make a POST /v3/domains/{domain_id}/verify request for each verification type. When the record checks out, status is done.
curl --request POST \ --url "https://api.us.nylas.com/v3/domains/${DOMAIN_ID}/verify" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY" \ --header "Content-Type: application/json" \ --data '{ "type": "ownership" }'{ "request_id": "2946921782-6e0655e8-2280-4669-ad0f-749c6d2943f0", "data": { "domain_id": "0a2171c6-c298-4671-8b82-d832a7fd5170", "attempt": { "type": "mx", "options": { "host": "@", "type": "MX", "value": "mx.us.nylas.email" } }, "status": "done", "created_at": 1794254567, "message": "MX records verified successfully. Domain is configured to receive mail through mx.us.nylas.email" }}If status is failed, wait a few minutes and try again. Ownership and MX records usually verify right away. SPF, DKIM, and feedback records can take a few minutes. DNS changes can take up to 24 hours to propagate.
List domains
Section titled “List domains”Make a GET /v3/domains request to list your organization’s domains, newest first. To find a specific domain, add the domain query parameter with its address.
curl --request GET \ --url "https://api.us.nylas.com/v3/domains?limit=50" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY"To get the next page, pass next_cursor as page_token. Every page that returns domains includes next_cursor. You’ve reached the end of the list when a page returns no domains.
Get a domain
Section titled “Get a domain”Make a GET /v3/domains/{domain_id} request to get a domain and see which verification types are complete. You can use the domain address in place of the domain ID.
curl --request GET \ --url "https://api.us.nylas.com/v3/domains/${DOMAIN_ID}" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY"Update a domain’s name
Section titled “Update a domain’s name”Make a PUT /v3/domains/{domain_id} request to rename a domain. The name is the only field you can change. To use a different address, register a new domain and delete the old one.
curl --request PUT \ --url "https://api.us.nylas.com/v3/domains/${DOMAIN_ID}" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "Transactional mail (US)" }'Delete a domain
Section titled “Delete a domain”Make a DELETE /v3/domains/{domain_id} request to remove a domain from your organization.
curl --request DELETE \ --url "https://api.us.nylas.com/v3/domains/${DOMAIN_ID}" \ --header "Authorization: Bearer $NYLAS_DOMAINS_KEY"Troubleshoot Manage Domains API errors
Section titled “Troubleshoot Manage Domains API errors”Most errors come from the API key’s permissions or the request body. Nylas rejects request bodies that include fields the endpoint doesn’t accept.
| Status | Message | Fix |
|---|---|---|
403 | Principal is missing the required permission | Add all 4 Domains permissions to the key’s principal. |
400 | field 'name' required | Include both name and domain_address when you register a domain. |
400 | Domain with the same domain address already exists | Your organization already registered this domain. List domains to find it. |