One Agent Identity Per Customer: Multi-Tenant Email

Provisioning a tenant-scoped email identity for your SaaS is one POST:

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": "[e-mail]"
    }
  }'

No OAuth dance, no refresh token — just an address on a registered domain. The response comes back already valid:

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "provider": "nylas",
    "grant_status": "valid",
    "email": "[e-mail]",
    "scope": [],
    "created_at": 1742932766
  }
}

The data.id is a grant_id that works with every existing Nylas endpoint, and the account is live immediately. That's the primitive behind a multi-tenant pattern worth knowing: one Agent Account per customer, on each customer's own verified domain, all managed from a single application. (Agent Accounts are in beta, so the surface may shift before GA.)

The architecture in one paragraph

Your app runs [e-mail], [e-mail], and so on — same code path, different identities. Each account has its own policy, its own send quota, and its own sender reputation. A single application can manage accounts across an unlimited number of registered domains, so tenant count is a billing question, not an architectural one. Customer A's deliverability problems stay Customer A's; nothing they do contaminates Customer B's mail.

Domains: register once, mint accounts forever

The provisioning docs lay out two domain strategies you can mix freely in one application:

Strategy	Address format	Setup
Trial domain	alias@<your-application>.nylas.email	None — instant
Your own domain	[e-mail]	MX + TXT records at the DNS provider

For the per-customer pattern, each tenant brings their domain. You register it once per organization (picking the US or EU data center region), the customer publishes the MX record (routes inbound to the platform) and TXT records (ownership proof plus SPF/DKIM for outbound), and verification flips to verified automatically once DNS propagates. From then on you create as many accounts under it as your plan allows.

Two field-tested recommendations from the docs: prototype on *.nylas.email and move to custom domains before launch, and prefer a dedicated subdomain like agents.customer-a.com so agent sender reputation is isolated from the customer's primary marketing domain. The same mechanism handles environment separation — agents.staging.yourcompany.com next to agents.yourcompany.com on one application keeps staging traffic off the production domain. High-volume senders sometimes go further and shard outbound across sales-a.yourcompany.com, sales-b.yourcompany.com purely for reputation isolation.

Workspaces are the tenant boundary

Notice the workspace_id in the request up top. Policies and rules — send limits, spam detection, retention, inbound filtering — apply through workspaces, not individual grants. Place each tenant's accounts in their own workspace and the whole tenant inherits its policy in one move.

The placement rules are worth knowing precisely:

• Pass workspace_id explicitly and the account lands there, picking up that workspace's limits, spam settings, and rules.
• Omit it, and the account is auto-grouped into a workspace whose domain matches the email address (when auto_group is enabled), or falls back to your application's default workspace.
• Move an existing account later with PATCH /v3/grants/{grant_id} and a new workspace_id.

For multi-tenant SaaS, that auto-group behavior is a nice default: accounts on customer-a.com cluster together without bookkeeping on your side. But explicit workspace_id per tenant is the predictable choice once policies differ between customers.

Fleet operations without leaving the terminal

The API call above is what your provisioning service runs; for day-to-day operations across tenants, the CLI exposes the same lifecycle:

nylas agent account create [e-mail]
nylas agent account list --json
nylas agent account get [e-mail]
nylas agent status              # connector readiness
nylas agent policy list         # policies attached to accounts
nylas agent account delete [e-mail] --yes

Agent Accounts also show up in nylas auth list alongside connected OAuth grants, which is a useful reminder of the design: to the rest of the platform, a tenant's agent is just another grant. There's a Dashboard path too (Agent Accounts → Accounts → Create account), handy for support staff who need to inspect a tenant's inbox without shipping code.

Quotas and the optional human door

Per-tenant quota math starts from the platform defaults: 200 messages per account per day on the free plan (paid plans have no daily cap by default), and a stricter per-workspace quota can be set through a policy when a tenant's use case warrants it. Storage runs 3 GB per organization on the free plan, with more on paid tiers.

If a tenant wants their staff to supervise the agent's mailbox from Outlook or Apple Mail, set an app_password at creation — 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. It's bcrypt-hashed on write (you can reset it, never read it back), and without it, IMAP/SMTP access simply stays disabled. That's a sensible per-tenant toggle: API-only for most, protocol access for the customers who ask.

Verifying a tenant is live

After provisioning, the smoke test is satisfyingly boring: send a test email to the new address from any external client, then list the mailbox —

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 arrives as mail lands, shaped identically to the same event for any connected grant — branch on provider: "nylas" when one handler serves both kinds of accounts.

Two questions that come up in design reviews

What happens if a tenant's domain verification stalls? Nothing breaks — the domain just stays unverified and you can't mint accounts on it yet. Registration is per-organization and verification flips automatically when DNS propagates, so the onboarding flow should poll domain status rather than assume it. Until then, the tenant can run on your trial domain.

Can we change a tenant's policy without touching accounts? Yes — that's the point of routing policy through workspaces. Swap or edit the workspace's policy and every Agent Account in it inherits the change; nothing is configured per-grant.

The end-to-end tenant onboarding flow — register domain, wait for verified, create workspace, provision account, smoke-test — is automatable from your existing provisioning code, and the trial-domain path lets you build it before any customer DNS exists. Sketch yours as a single idempotent onboardTenant(domain, alias) function and see how far one afternoon gets you.

Comments

[TopStar AI]

Great writeup — the dedicated agent mailbox is the part that clicks for me. Turning it from a send pipe into one threaded conversation, with the sent folder doubling as an audit trail, solves continuity and reconciliation in a single move. The confirm-before-send gate is smart too; STT mishearing a recipient is exactly how trust erodes fast.
I build voice and multi-agent systems — Python/FastAPI, LLM function-calling, RAG — and have been working through this same follow-up-artifact problem on a few projects. Would love to connect and compare notes, and happy to collaborate if you're building in this space. Nice work.