DNS for Agent Mailboxes: MX and TXT Records Explained

You've created an agent mailbox at [e-mail], the dashboard says the domain isn't verified, and your DNS provider is showing you a form with record types you haven't touched since you set up Google Workspace. Two records stand between you and a working inbox: an MX record and some TXT records. Here's what each one actually does.

Quick context first: Nylas Agent Accounts (currently in beta) are hosted mailboxes for AI agents, and every account lives on a domain. A shared *.nylas.email trial domain needs zero DNS work; your own domain needs records published before it can host accounts. This post is about the second path.

The MX record: where inbound mail goes

MX (Mail Exchange) records are how the rest of the internet finds your mailboxes. When someone emails [e-mail], their mail server looks up the MX record for yourcompany.com and delivers to whatever host it names. No MX pointing at the mailbox provider, no inbound mail — outbound might work, but replies vanish.

When you register a domain in the Dashboard (or through the API), Nylas generates the exact MX record you need to publish at your DNS provider. It routes inbound mail for that domain to the hosted inbound infrastructure, where it's processed and delivered to the right agent's inbox.

This is also why the docs push hard on one piece of advice: use a dedicated subdomain. If you point yourcompany.com's MX at the agent infrastructure, you've rerouted your entire company's email. Point agents.yourcompany.com instead:

# What your DNS zone ends up looking like (illustrative)
yourcompany.com.         MX  →  your existing mail host (unchanged)
agents.yourcompany.com.  MX  →  the Nylas-generated mail host

Your team's mail keeps flowing where it always did; only addresses under the subdomain route to agent mailboxes.

The TXT records: proof and permission

TXT records are free-form DNS entries that other systems read for verification and policy. For a custom agent domain they do two jobs, per the provisioning docs:

1. Prove ownership. A generated verification value that only someone with control of the DNS zone could publish. This is what stops a stranger from registering your domain and minting mailboxes on it.
2. Configure SPF and DKIM for outbound. SPF declares which servers may send mail for your domain; DKIM publishes the public key that lets receiving servers validate message signatures. Without these, outbound mail from your agents is far more likely to land in spam — receiving servers treat unauthenticated mail from an unknown domain with deep suspicion.

So the MX record is about receiving, and the TXT records are about trust — proving you own the domain and telling the world your agents' outbound mail is legitimate.

How verification actually works

The flow has exactly three steps:

1. Register the domain from the Dashboard's organization settings, picking the data-center region (US or EU) where your application lives. Registration happens once per organization; after that, you can create as many Agent Accounts under the domain as your plan allows.
2. Publish the generated records at your DNS provider — the MX record plus the TXT records from above.
3. Wait. Once the records propagate, verification is automatic. No "verify now" button to mash — the domain status moves to verified on its own, and the domain can host accounts.

Propagation is the only genuinely unpredictable part. DNS changes can be visible in minutes or take longer depending on your provider and TTLs, so if verification hasn't flipped immediately, give it time before assuming you've mistyped a record.

After verification: one command per mailbox

With the domain verified, account creation is trivial. From the CLI:

nylas agent account create [e-mail]
nylas agent account list
nylas agent status   # confirm the connector is ready

Or one API call to POST /v3/connect/custom with "provider": "nylas" and the email address — no OAuth, no refresh token. The response is worth seeing once, because it's the whole handoff:

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "provider": "nylas",
    "grant_status": "valid",
    "email": "[e-mail]",
    "scope": [],
    "created_at": 1742932766
  }
}

data.id is the grant_id you'll use for every message and event on that mailbox, and grant_status is already valid — no pending state, no confirmation email.

Two flags worth setting at creation

Both are optional, and both are easier to set now than to retrofit:

• workspace_id (a top-level field, not a settings entry) places the account in a specific workspace, so it inherits that workspace's policy limits, spam settings, and rules from its first second of existence. Omit it and the account is auto-grouped into a workspace whose domain matches the address (when auto_group is enabled) or lands in the application's default workspace. You can move it later with PATCH /v3/grants/{grant_id}.
• app_password enables IMAP and SMTP access, so a human can open the agent's mailbox in Outlook or Apple Mail. The password must be 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. It's stored as a bcrypt hash — Nylas validates it on write and you can't retrieve it afterward, only reset it. Skip it and protocol-level access stays disabled, which is a sensible default for fully autonomous agents.

One domain registration also scales further than you might expect: a single application can manage accounts across any number of registered domains. The docs describe teams using that for per-customer domains, sender-reputation isolation (splitting volume across sales-a.yourcompany.com and sales-b.yourcompany.com), and keeping staging traffic on agents.staging.yourcompany.com away from production.

Two questions that come up every time

Can I mix trial and custom domains in one application? Yes — many teams prototype on the zero-DNS alias@<your-application>.nylas.email trial domain and register the custom domain in parallel, moving agents over before launch. Same application, same code, only the address changes.

Do I re-register the domain for every environment? No — registration is once per Nylas organization, and after that you create as many Agent Accounts under the domain as your plan allows. For environment separation, the docs recommend separate subdomains (agents.staging.yourcompany.com next to agents.yourcompany.com) rather than separate registrations of the same name.

If you just want to see the records in action, register a domain, publish the two record types, and send a test email to the new address from your phone — then list the mailbox via GET /v3/grants/{grant_id}/messages and watch it arrive. Stuck on a verification that won't flip? Drop your DNS provider in the comments; propagation quirks tend to cluster by provider.