How many email domains should one application be allowed to manage? Most email platforms answer with a number and a pricing tier. Nylas Agent Accounts — programmatic mailboxes currently in beta — answer with: unlimited. One application can host agent mailboxes across any number of registered domains, and that single design decision shapes how you organize tenants, environments, and brands.
Here's how multi-domain setups actually work, and the three patterns the provisioning docs call out.
Every agent mailbox lives on a domain. Before creating an account, you register the domain once per organization — then create as many accounts under it as your plan allows. Registration takes three steps: add the domain in the Dashboard (picking the US or EU data center region), publish the generated DNS records at your provider, and wait for automatic verification. Two record types do the work: an MX record routes inbound mail, and TXT records prove ownership and set up SPF/DKIM for outbound.
Once a domain's status hits verified
, account creation is one call:
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": "sales-agent@agents.yourcompany.com"
}
}'
The response includes a grant_id
— the handle for every subsequent messages, calendar, and webhook call. No refresh token, because there's no OAuth provider behind it. If you prefer the terminal, the Nylas CLI wraps the same flow: nylas agent account create agent@agents.yourcompany.com
provisions the grant and prints its ID, and nylas agent account list
shows everything on the application.
Multi-tenant SaaS is the obvious case. Your customers bring their own domains; you register each one and provision agent mailboxes on their behalf — scheduling@customer-a.com
, scheduling@customer-b.com
— all running in one application with the same code path. Each customer's accounts can sit in their own workspace with their own policy, which means per-customer send quotas, retention windows, and spam settings without forking anything.
The part that matters commercially: each domain carries its own sender reputation. Customer A's aggressive outreach campaign can't poison Customer B's deliverability.
That same isolation property works inside one company. The docs describe splitting high-volume outbound across sales-a.yourcompany.com
, sales-b.yourcompany.com
, and so on, so issues on one domain don't contaminate the others. If a campaign on sales-a
triggers complaints, sales-b
keeps delivering while you fix it.
Related advice worth taking even at small scale: use a dedicated subdomain for production agents — agents.yourcompany.com
rather than yourcompany.com
— so agent traffic never touches the reputation of your primary marketing domain. A misbehaving bot shouldn't be able to hurt the deliverability of your CEO's email.
Staging traffic on the production domain is a classic self-inflicted wound. The multi-domain model fixes it cleanly: register agents.staging.yourcompany.com
and agents.yourcompany.com
in the same application. Your staging environment provisions real, working mailboxes — actual sends, actual receives, actual webhooks — without any risk to production sender reputation.
For even cheaper experimentation, there's a zero-DNS option: trial domains. Every application can register a *.nylas.email
subdomain from the Dashboard with no DNS setup at all, giving you addresses like test@your-application.nylas.email
instantly. You can mix trial and custom domains freely in one application — a common path is prototyping on the trial domain and registering a custom one before launch.
Domains decide what an address looks like; workspaces decide how it behaves. Policies and rules attach to workspaces, not to individual grants — so in a multi-domain setup, the workspace assignment at creation time is the step that actually wires a new account into the right tenant's quotas and spam settings. Pass workspace_id
as a top-level field (not inside settings
):
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",
"workspace_id": "<WORKSPACE_ID>",
"settings": {
"email": "scheduling@customer-a.com"
}
}'
If you omit workspace_id
, there's a sensible fallback chain: with auto_group
enabled, the account is grouped into a workspace whose domain
matches its email address — which pairs naturally with the per-customer-domain pattern, since each customer's accounts cluster automatically. Otherwise it lands in your application's default workspace. And nothing is permanent: PATCH /v3/grants/{grant_id}
with a new workspace_id
moves an existing account, so you can re-shard tenants later without re-provisioning.
One operational note for multi-domain apps: the message.created
webhook payload has the same shape for every grant, so a single handler serves all domains. Branch on the grant's provider
("nylas"
) if you also have connected Gmail or Outlook grants in the same application and need to tell agent deliveries apart.
Since domains are unlimited, the constraints sit elsewhere. From the overview docs, the free-plan numbers:
Notice that none of these are per-domain. Send limits attach to accounts, storage attaches to the organization, and policies attach to workspaces. Domains are purely an organizational and reputational boundary — which is exactly why you can have as many as your architecture wants.
Putting it together, a multi-tenant layout might look like:
Application (one API key)
├── customer-a.com → workspace A → policy: 50 sends/day
│ ├── scheduling@customer-a.com
│ └── support@customer-a.com
├── customer-b.com → workspace B → policy: defaults
│ └── scheduling@customer-b.com
├── agents.yourcompany.com → internal workspace
│ └── ops-agent@agents.yourcompany.com
└── your-app.nylas.email → default workspace (dev/test)
One API key, one webhook subscription, one code path — and clean boundaries for billing, reputation, and blast radius.
If you're designing a multi-tenant agent product, start by sketching your domain map before you provision anything: which domains are customer-owned, which are yours, and which workspace each feeds into. Then walk through the provisioning guide and register your first two — one trial, one custom — and compare the setup friction yourself.