Source: https://cli.nylas.com/guides/multi-tenant-agent-inboxes

# Multi-Tenant Agent Inboxes

Give every SaaS customer its own AI agent inbox. How to address, route, and isolate one managed mailbox per tenant — and when a shared inbox is enough.

Written by [Caleb Geene](https://cli.nylas.com/authors/caleb-geene) Director, Site Reliability Engineering

Updated June 14, 2026

> **TL;DR:** Give each tenant its own agent inbox like `acme@yourapp.nylas.email` so the agent that serves a customer can only ever read that customer's mail. The inbox address is the tenant boundary — no shared queue, no cross-tenant reads. Below a few hundred tenants this is the clean default; past that, weigh a shared inbox with tenant tags.

## What is a multi-tenant agent inbox architecture?

A multi-tenant agent inbox architecture gives each customer of a SaaS product its own managed agent inbox, so the AI agent serving that customer reads and sends only their mail. The inbox address itself is the isolation boundary: tenant `acme` gets `acme@yourapp.nylas.email`, and nothing the agent does can reach another tenant's inbox. One workspace holds many accounts.

One application provisions a separate agent inbox per tenant: acme, globex, and initech each get an isolated managed mailbox with no shared stateYour applicationone workspaceacme@app.nylas.emailisolated inboxglobex@app.nylas.emailisolated inboxinitech@app.nylas.emailisolated inbox

This is the email equivalent of a [per-tenant database schema](https://learn.microsoft.com/en-us/azure/azure-sql/database/saas-tenancy-app-design-patterns). Instead of one shared mailbox with a tenant column every query must filter on, each tenant has a physically separate inbox, so a routing bug can't leak one customer's mail to another. The trade-off is account count, which is why the decision below matters once you pass a few hundred tenants.

## Why give each tenant its own agent inbox?

Per-tenant inboxes isolate failure, data, and blast radius — the core goal of [tenant isolation](https://docs.aws.amazon.com/whitepapers/latest/saas-architecture-fundamentals/tenant-isolation.html) in any SaaS design. A misbehaving agent can only touch the one inbox it owns, a compromised tenant can't read another's threads, and every customer gets a clean per-tenant audit trail with no filtering. Suspending a single tenant is one grant operation that leaves every other tenant untouched.

Isolation also shrinks the prompt-injection surface. With a shared inbox, one poisoned message sits in the same queue as every tenant's mail, so an injection that escapes a filter has the whole customer base in reach. With per-tenant inboxes, the same payload is trapped in one account that holds only that tenant's data — the blast radius is exactly one customer, not thousands.

## How do you address one inbox per tenant?

Derive each address from a stable tenant slug, not a display name, so it never changes when the customer renames their company. Provision the inbox at signup with `nylas agent account create`, store the returned grant against the tenant id, and you have a deterministic mapping from tenant to inbox. For bulk-creating hundreds of these idempotently, see the provisioning-at-scale guide below.

```bash
# Provision a tenant's inbox at signup, keyed by a stable slug
nylas agent account create acme@yourapp.nylas.email --json

# List the fleet to reconcile inboxes against your tenant table
nylas agent account list --json
```

Keep the slug-to-grant mapping in your own database as the source of truth. The `account list` output lets you reconcile that table against the live fleet, so an inbox that exists without a tenant row — or a tenant without an inbox — surfaces in one diff rather than a support ticket.

## How does inbound mail route to the right tenant?

Routing is implicit: because each tenant has a separate inbox, the inbox a message arrives in is the tenant it belongs to. There is no shared queue to demultiplex and no tenant-id header to trust. The agent process for tenant `acme` reads only the acme grant, so it physically cannot pull another tenant's mail.

The `nylas email list --unread --json` command scopes to whichever grant the agent runs under, so the same command serves every tenant without a tenant filter in the query. Each grant carries its own OAuth access token, valid for up to 3,600 seconds and invalidated the moment that grant is revoked, so isolation holds at the credential layer too. That removes the most common multi-tenant bug entirely — a forgotten `WHERE tenant_id =` clause can't leak data that was never in the same inbox.

```bash
# The agent runs under one tenant's grant; the read is already scoped
nylas email list --unread --json
```

## When should you use a shared inbox instead?

Per-tenant inboxes aren't free. The free tier covers 5 accounts, and at tens of thousands of tiny or free-plan tenants the account count and cost outgrow the isolation benefit. For that long tail, a shared inbox with a tenant tag on each message is the pragmatic choice — you trade physical isolation for a logical one you enforce in code, one of the standard [multi-tenant architecture](https://learn.microsoft.com/en-us/azure/architecture/guide/multitenant/overview) models.

A workable rule: give paid tenants their own inbox and pool free-tier tenants into a shared inbox keyed by a reply-to tag or a plus-address. You keep hard isolation where the data is sensitive and accept logical isolation where the volume is high and the stakes are low. The cost of the shared path is that one filtering bug can cross tenants, so the tagging logic needs the same care a shared database schema does.

## Next steps

- [Provision Agent Accounts at Scale](https://cli.nylas.com/guides/provision-agent-accounts-at-scale) — bulk-create, idempotency, shared guardrails, and fleet teardown for these inboxes
- [Getting Started with Agent Accounts](https://cli.nylas.com/guides/getting-started-agent-accounts) — the workspace model and grant lifecycle behind each tenant inbox
- [Agent Account vs Delegated OAuth](https://cli.nylas.com/guides/agent-account-vs-delegated-oauth) — why a managed inbox per tenant beats OAuth into each customer's mailbox
- [Agent Rules and Policies](https://cli.nylas.com/guides/agent-rules-and-policies) — the per-tenant outbound rules and send caps that contain each agent
- [Full command reference](https://cli.nylas.com/docs/commands) — every `nylas agent` subcommand and flag

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/