Set up DNS records for Agent Accounts

Agent Accounts are in beta. The API and features may change before general availability.

A custom Agent Account domain is ready only after you publish the DNS records Nylas generates for it and verifies them. This page shows how to enter those records in four common DNS providers and how to choose a DKIM key size. To register the domain and fetch the record values first, see Provisioning and domains and Managing domains.

This page assumes you already have the record values. Register the domain, then call the domain /info endpoint (or open the Dashboard) to get the exact host, type, and value for each record. Managing domains covers that flow and which record verifies what.

Before you begin

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 or the Manage Domains API.
• Fetch the records with the domain /info endpoint, once per verification type.
• Or get them from the Dashboard. The Dashboard 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.
• Keep the /info response open while you work. Some values are regenerated if they expire, so always paste the freshest value.

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.

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). 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.

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

What’s next

• Provisioning and domains: register a domain and create accounts on it
• Managing domains: the verification API, record types, and DKIM key-size option
• Email deliverability for Agent Accounts: DMARC setup and sender-reputation practices