Skip to content
Skip to main content

Manage email domains with the Domains API

Last updated:

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

Get the DNS record for each verification type, add the records, then verify each type. A verify call that returns 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/domains returns the domain ID. Every verified_* field starts as false.
  • Your backend: Get the DNS records: POST /v3/domains/{domain_id}/info once per type. Values expire after 2 days.
  • 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 /v3/domains/{domain_id}/verify once per type.
    • status: failed → Not confirmed yet: Wait a few minutes and call /verify again.
  • Your app: Send or receive mail: Use the domain with Transactional Send or Agent Accounts. (status: done)

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.

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.

  1. In the Dashboard, go to Nylas IAM and select Create principal. Give the principal a name that describes the service that will use it.

    The Name step of the Create principal dialog, with the name Domain provisioning service.

  2. Select Next and choose Organization as the resource binding.

    The Resource step of the Create principal dialog, with the Organization binding selected.

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

    The Direct permissions section, with Read domains, Create domains, Update domains, and Delete domains selected.

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

    The Create IAM API key dialog for the Domain provisioning service principal.

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

    The Credentials tab after you create the key, with the key hidden and a Copy button.

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.

The Principals tab, showing the Domain provisioning service principal with the 4 Domains permissions at the Organization level.

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.

New domains start unverified.

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.

TypeRequired forRecord
ownershipAll domainsTXT record that proves you own the domain.
dkimTransactional Send, Agent AccountsTXT record for DKIM signing.
spfTransactional Send, Agent AccountsTXT record that authorizes Nylas to send.
feedbackTransactional Send, Agent AccountsMX record for bounce reports.
mxAgent AccountsMX record that routes incoming mail.

Nylas doesn’t check DMARC or ARC records, but we recommend publishing a DMARC record to improve deliverability.

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.

Record values expire after 2 days. If they expire before you verify the domain, request them again.

Record hosts are relative to your root domain, and @ is the root domain itself. For example.com, the records look like this:

TypeRecordHostValue
ownershipTXT@Unique to your domain
mxMX@mx.us.nylas.email
spfTXTsendv=spf1 include:amazonses.com ~all
dkimTXTnylas._domainkeyUnique to your domain
feedbackMXsendfeedback-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.

Make a POST /v3/domains/{domain_id}/verify request for each verification type. When the record checks out, status is done.

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.

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.

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.

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.

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.

Make a DELETE /v3/domains/{domain_id} request to remove a domain from your organization.

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.

StatusMessageFix
403Principal is missing the required permissionAdd all 4 Domains permissions to the key’s principal.
400field 'name' requiredInclude both name and domain_address when you register a domain.
400Domain with the same domain address already existsYour organization already registered this domain. List domains to find it.