Managing Many Domains in One Application

Nylas Agent Accounts, currently in beta, allow an application to manage unlimited email domains, with each domain carrying its own sender reputation to prevent cross-contamination. The provisioning process involves registering a domain, verifying it via DNS records, and then creating agent mailboxes with a single API call. Multi-domain setups enable patterns like multi-tenant SaaS, isolation of high-volume outbound traffic, and separate staging environments without risking production reputation.

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 https://developer.nylas.com/docs/v3/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 https://developer.nylas.com/docs/v3/agent-accounts/provisioning/ 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 https://cli.nylas.com/ 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 https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-lists/ , 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 https://developer.nylas.com/docs/v3/agent-accounts/ , 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 https://developer.nylas.com/docs/v3/agent-accounts/provisioning/ and register your first two — one trial, one custom — and compare the setup friction yourself.