Trial Domains vs Custom Domains for Agent Accounts

A team I'll generalize from experience: they spend a sprint planning their AI agent's email integration, then stall for a week because nobody can get a DNS change through the infrastructure review queue. The agent code was done. The mailbox didn't exist yet, because the mailbox needed a domain, and the domain needed MX records, and the MX records needed a ticket.

This is exactly the gap trial domains exist to close. With Nylas Agent Accounts (currently in beta), every mailbox lives on a domain — and you get two very different ways to supply one.

Both produce identical mailboxes from the API's perspective: same grant_id

, same Messages and Events endpoints, same message.created

webhooks. The difference is entirely about who controls the domain and what the address says about you.

Trial subdomains under *.nylas.email

are provided per application. Register one from the Dashboard and you can create accounts on it immediately — no DNS provider, no infra ticket, no waiting on propagation:

nylas agent account create test@your-application.nylas.email

Or through the API with POST /v3/connect/custom

and "provider": "nylas"

— no refresh token, just the address:

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": { "email": "test@your-application.nylas.email" }
  }'

The quickstart goes from nothing to a sending-and-receiving mailbox in under 5 minutes, and the trial domain is the reason that number is honest. Verification emails arrive, webhooks fire, calendars RSVP. Everything works.

And it's genuinely testable end to end. Send a message to the new address from your personal account, then list the inbox:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5" \
  --header "Authorization: Bearer $NYLAS_API_KEY"

If you've registered a message.created

webhook, the notification lands as soon as the mail does — same payload shape as any other grant. The full receive-and-respond loop you'll run in production is exercisable on day one, on a domain you didn't have to configure.

What a trial domain isn't is a brand. test@your-application.nylas.email

screams "automated system" to every recipient, and you don't own the reputation story for a shared infrastructure domain. For an internal prototype, who cares. For a sales agent emailing prospects, it matters a lot.

Registering your own domain means publishing the MX record (routes inbound mail) and TXT records (prove ownership, configure SPF/DKIM for outbound) that the platform generates for you. Once they propagate, verification is automatic — the status flips to verified

and the domain can host accounts. You register a domain once per organization, picking the US or EU data-center region, then create as many accounts under it as your plan allows.

In exchange for that setup you get:

assistant@yourcompany.com

reads like a colleague, not a test rig.agents.yourcompany.com

so agent traffic can't dent your primary marketing domain.sales-a

and sales-b

subdomains, or agents.staging.yourcompany.com

keeping test traffic off production.Here's what makes the two-tier model work in practice: you don't choose once. You can mix both strategies in one application, and the documented pattern is to prototype on *.nylas.email

and move to a custom domain before launch.

"Move" is lighter than it sounds. Agent Accounts are created per address, so migrating means registering the custom domain, waiting for verification, and provisioning new accounts on it — your application code is unchanged because everything keys off grant_id

, not the address. Start the DNS registration early (it's the only step with real wall-clock wait), and build the whole agent against a trial-domain mailbox in parallel. By the time the domain verifies, you swap in a production grant ID and you're done.

Worth being precise here, because "trial" suggests a degraded product and that's not what this is:

*.nylas.email

or your own domain. Moving to a custom domain doesn't raise quotas; upgrading your plan does.One wrinkle worth planning for: policies and rules attach through workspaces. Pass a workspace_id

when creating the account and it inherits that workspace's send limits, spam settings, and mail rules; omit it and the account lands in your application's default workspace (or is auto-grouped into a workspace matching the email's domain when auto_group

is enabled). Set your production workspace up before the migration so the new accounts inherit the right guardrails on day one.

If you've got an agent idea queued behind an infra ticket right now, flip the order: grab a trial domain today, build the full loop against it, and let the provisioning guide walk you through the custom-domain registration while you ship. The quickstart is the fastest on-ramp — what would your agent's production address be?