Managing Many Domains in One Application

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.

Domains are the unit of identity

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.

Pattern 1: per-customer domains

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.

Pattern 2: reputation isolation

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.

Pattern 3: environment separation

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.

Routing accounts into workspaces

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.

Where the limits actually live

Since domains are unlimited, the constraints sit elsewhere. From the overview docs, the free-plan numbers:

Send rate: 200 messages per account per day (paid plans have no daily cap by default)
Storage: 3 GB per organization
Retention: 30 days inbox, 7 days spam, configurable through policies

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.

A sketch of a tenant model

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.

推荐订阅源

DEV Community