You've created an agent mailbox at agent@yourcompany.com
, 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.
MX (Mail Exchange) records are how the rest of the internet finds your mailboxes. When someone emails agent@yourcompany.com
, 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:
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.
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:
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.
The flow has exactly three steps:
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.
With the domain verified, account creation is trivial. From the CLI:
nylas agent account create agent@agents.yourcompany.com
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": "agent@agents.yourcompany.com",
"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.
Both are optional, and both are easier to set now than to retrofit:
workspace_id
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
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.
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.