# Set up domains for Agent Accounts

Source: https://developer.nylas.com/docs/v3/agent-accounts/dns-provider-setup/

Every Agent Account lives on a domain. You can host on a shared Nylas trial domain (instant, with no DNS setup) or a custom domain you own (MX and TXT records at your DNS provider). This page helps you pick a strategy, then walks through registering a custom domain, publishing its DNS records at four common providers, and verifying them. For the underlying registration and verification API, see [Managing domains](/docs/v3/email/domains/).

## Choose a domain strategy

| Strategy | Address format | Setup | When to use |
| --- | --- | --- | --- |
| **Nylas trial domain** | `alias@<your-application>.nylas.email` | None (register from the Dashboard) | Prototyping, local testing, demos |
| **Your own domain** | `alias@yourdomain.com` | MX and TXT records at your DNS provider | Production, customer-facing agents, branded mail |

You can mix both strategies in one Nylas application. Many customers prototype on `*.nylas.email` and move to a custom domain before launch. A trial domain needs no DNS setup, so if you picked one you can skip ahead to [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/); the rest of this page covers custom domains.

## Register a custom domain

You register a domain once per Nylas organization, then create as many Agent Accounts under it as your plan allows.

1. **Register the domain with Nylas.** From the [Dashboard](https://dashboard-v3.nylas.com/organization/domains), add the domain and pick the data center region (US or EU) where your application lives. You can also register through the API; see [Managing domains](/docs/v3/email/domains/).
2. **Publish DNS records at your DNS provider.** Nylas generates the MX record (routes inbound mail to Nylas) and TXT records (prove ownership and configure SPF/DKIM for outbound) you need to publish. Add them at your DNS provider using the provider-specific steps below.
3. **Wait for verification.** Once the records propagate, Nylas verifies them automatically. The domain status moves to `verified` and is ready to host Agent Accounts.

We recommend a dedicated subdomain for production use (for example, `agents.yourcompany.com`) so that sender reputation on Agent Accounts is isolated from your primary marketing domain.

## Before you begin

> **Info:** 
> **You need the record values before you publish DNS.** After you register the domain, call the domain `/info` endpoint (or open the Dashboard) to get the exact host, type, and value for each record. [Managing domains](/docs/v3/email/domains/) covers that flow and which record verifies what.

You need a domain registered with Nylas and the set of DNS records its `/info` endpoint returns. A custom Agent Account domain uses up to five records: a TXT record for ownership, a TXT record for DKIM, a TXT record for SPF, an MX record for the feedback loop, and an MX record that delivers inbound mail to your Agent Accounts. Each record arrives as a `host`, `type`, and `value` you copy verbatim into your DNS provider.

- **Register the domain** from the [Dashboard](https://dashboard-v3.nylas.com/organization/domains) or the [Manage Domains API](/docs/v3/email/domains/).
- **Fetch the records** with the domain `/info` endpoint, once per verification type.
- **Or get them from the Dashboard.** The [Dashboard](https://dashboard-v3.nylas.com/organization/domains) lists every record's host, type, and value with a per-record copy button, plus a **Copy zone file** button that copies all records at once. To publish them in one step, see [Import all records at once](#import-all-records-at-once-with-a-zone-file).
- **Keep the `/info` response open** while you work. Some values are regenerated if they expire, so always paste the freshest value.

> **Info:** 
> **Also set up DMARC.** DMARC isn't one of the records Nylas issues, and it isn't part of verification, but adding it protects your domain from spoofing and improves deliverability. It's a separate TXT record at `_dmarc.<your-domain>` that you roll out in stages. See [Set up DMARC](/docs/v3/agent-accounts/deliverability/#set-up-dmarc).

## How DNS fields map to a Nylas record

Every provider asks for the same three things under different labels, so the mapping is identical no matter where your domain is hosted. The `host` from Nylas goes in the **Name** or **Host** field, the `type` selects the record type, and the `value` goes in the **Value** or **Content** field. Two rules trip people up most often.

- **Host.** Use `@` for the root domain, or just the subdomain label (for example, `agents`). Most providers append your domain automatically, so don't paste the full name twice.
- **MX records carry a priority.** The feedback and inbound MX records need a priority number alongside the mail server. Use the priority from the Nylas record value; a lower number is higher priority.

## Choose your DKIM key size (1024-bit or 2048-bit)

Nylas signs outbound mail with a **1024-bit** DKIM key by default because the public key fits in a single DNS TXT record. A DNS TXT string holds at most 255 characters, and a 1024-bit public key stays under that limit, so you paste one clean value. A 2048-bit key is longer than 255 characters and has to be split into multiple quoted strings inside one record, where some provider editors handle the split awkwardly and a single mistake silently breaks signing.

If a security policy requires 2048-bit keys, request one when you fetch the DKIM record: pass `"options": { "use_2048_bit_key": true }` on the `/info` request for `type: "dkim"` (see [Managing domains](/docs/v3/email/domains/)). When you publish it, paste the value exactly as Nylas returns it, including the split into separate quoted strings, and confirm your provider didn't reorder or drop a segment.

## Import all records at once with a zone file

Instead of adding records one at a time, you can publish them in a single step. The Dashboard's **Copy zone file** button copies all of a domain's records as a BIND zone file, and three of the four providers below can import that file directly. It's the fastest way to set up a domain, with one important exception for DKIM in the warning below.

- **Cloudflare** imports from **DNS → Records → Import and Export**. The importer reads a file, so save the copied text as a `.txt` file first, then upload it.
- **Route 53** imports from a hosted zone's **Import zone file** option, where you paste the copied text directly.
- **GoDaddy** imports from **DNS → Actions → Import Zone File**, which also takes an uploaded file.
- **Namecheap** has no zone-file import in Advanced DNS, so add its records by hand with the steps below.

> **Warn:** 
> **Using a 2048-bit DKIM key? Add that record by hand.** A 2048-bit public key is too long for one DNS string, so it lives as a multi-string TXT record, and zone-file import doesn't always reassemble those strings correctly. To avoid silently breaking DKIM, import the zone file for the other records but enter the DKIM record manually, or verify the imported DKIM value matches what Nylas issued exactly. The default 1024-bit key imports cleanly, which is one more reason to stay on it unless a policy requires 2048-bit.

## Add records in Cloudflare

Cloudflare applies most DNS edits within seconds, which makes it a forgiving place to verify a domain. Records live under **DNS** in the dashboard, and TXT and MX records are never proxied, so there's no orange-cloud setting to worry about for any of the Nylas records.

1. Open your domain, then go to **DNS → Records** and select **Add record**.
2. Pick the **Type** (`TXT` or `MX`) that matches the Nylas record.
3. In **Name**, enter the record host (`@` for the root, or the subdomain label).
4. In **Content**, paste the value from the Nylas record. For MX, set **Mail server** to the target and **Priority** to the number from the record.
5. Leave **TTL** on **Auto** and select **Save**.

## Add records in Amazon Route 53

Route 53 is the most exacting of the four on long TXT values, so a 2048-bit DKIM key needs extra care here. Each quoted string in a TXT value is limited to 255 characters; a long key must be entered as several quoted strings, one per line, inside the same record. Records live under **Hosted zones**.

1. In **Hosted zones**, open the zone for your domain and select **Create record**.
2. Set **Record name** to the host and choose the **Record type** (`TXT` or `MX`).
3. For TXT, wrap the value in quotes. If a DKIM value exceeds 255 characters, enter each segment as its own quoted string on a new line.
4. For MX, use the `priority mail-server` format Route 53 expects (for example, `10 feedback.example.com`).
5. Leave the default TTL of 300 seconds and select **Create records**.

## Add records in GoDaddy

GoDaddy edits propagate within an hour for most changes, though it can take longer. DNS records are under **My Products → Domain → DNS** (the DNS Management screen). GoDaddy stores the root as `@` and appends your domain to whatever you type in the host field.

1. Open **DNS Management** for your domain and select **Add New Record**.
2. Choose the **Type** (`TXT` or `MX`) and put the host in **Name** (`@` or the subdomain label).
3. Paste the Nylas value into **Value**. For MX, set **Value** to the mail server and **Priority** to the record's number.
4. Leave **TTL** at the default of 1 hour and select **Save**.

## Add records in Namecheap

Namecheap keeps custom records under **Domain List → Manage → Advanced DNS**, and TXT and SPF entries go in the same **Host Records** table as MX. It has no zone-file import, so these manual steps are the only way to add records here. Changes usually resolve within 30 minutes. Namecheap uses `@` for the root domain and strips a trailing dot, so enter the host exactly as Nylas provides it.

1. From **Domain List**, select **Manage** on your domain, then open **Advanced DNS**.
2. Under **Host Records**, select **Add New Record** and pick the type (`TXT Record` or `MX Record`).
3. Put the host in **Host** and the Nylas value in **Value**.
4. For an MX record, set **Mail Server** to the Nylas target and choose the matching **Priority**.
5. Save with the green checkmark and leave **TTL** on **Automatic**.

## Verify the records and troubleshoot

After the records are live, trigger verification and let DNS propagate. Call the domain `/verify` endpoint (or use the Dashboard) once per type, as described in [Managing domains](/docs/v3/email/domains/). Verification usually succeeds within a few minutes, but DNS can take up to 24 hours depending on the record's TTL.

If a record won't verify, the value almost always differs from what Nylas issued: re-fetch it from `/info`, confirm you didn't paste your domain into the host twice, and check that a long DKIM value kept all of its quoted segments. DMARC and ARC are optional and aren't part of verification, so set up DMARC separately to protect your domain. See [Set up DMARC](/docs/v3/agent-accounts/deliverability/#set-up-dmarc).

## What's next

- [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/): create Agent Accounts on a verified domain
- [Managing domains](/docs/v3/email/domains/): the verification API, record types, and DKIM key-size option
- [Email deliverability for Agent Accounts](/docs/v3/agent-accounts/deliverability/): DMARC setup and sender-reputation practices