# Multi-tenant agent inboxes: isolate each customer

> How to give each customer or agent its own isolated inboxes inside one account: tenant boundaries, scoped API keys, webhooks, domains and plan limits.

Source: https://trotta.email/learn/multi-tenant-agent-inboxes

Multi-tenant agent inboxes give each customer, or each agent, its own isolated set of inboxes inside one account. The isolation should be enforced by the email platform, not by filters in your code: one workspace per tenant, an API key that reaches that workspace and nothing else, and webhooks that carry its events alone.

Updated November 20, 2026

## What does multi-tenant mean for agent inboxes?

Multi-tenant means one account serves many customers, and each customer's mail stays invisible to the others. A platform that runs agents for its customers needs this from its second customer on: the support agent for one company must never read, search or answer another company's mail.

Three things have to be kept apart: the data (inboxes, threads, messages), the credentials (API keys) and the event flow (webhooks and streams). A gap in any one of them is a leak between tenants.

## Where should the isolation be enforced?

Isolation should be enforced by the platform that stores the mail, at a boundary the API itself checks. The other way, one account-wide key and a customer filter in your own code, leaves every customer one missed filter away from another's inbox.

| Design | What keeps tenants apart | If a key leaks or a filter is missed |
| --- | --- | --- |
| One shared inbox, mail tagged by customer | Your code filters by tag | Every customer's mail is exposed |
| One inbox per customer, one account-wide key | Your code picks the inbox | Every inbox is exposed |
| One key per inbox | The API limits each key to its inbox | One inbox is exposed. A customer with several inboxes needs several keys |
| One workspace per customer | The API limits each key to its workspace | One customer's workspace is exposed |
| One account per customer | Separate accounts | One customer is exposed. Billing, limits and oversight are split too |

An agent adds a reason to want hard walls. A model that reads mail can be steered by what it reads. If an injected instruction tells one customer's agent to fetch another customer's thread, the request should fail at the API. It should not depend on the model saying no.

## How do pods isolate tenants in Trotta Mail?

Pods isolate tenants in Trotta Mail by giving each one a workspace with keys of its own: a key in a pod reaches that pod and nothing outside it. A pod holds agent inboxes, domains, API keys and webhooks.

Create one pod per customer, with a key that is outside every pod. A `client_id` makes the call idempotent: create again with the same value and you get the same pod.

```bash
curl -X POST https://api.trotta.email/v1/pods \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind", "client_id": "northwind"}'
```

201 Created:

```json
{
  "id": "pod_7hc2mxq4",
  "name": "Northwind",
  "client_id": "northwind",
  "counts": { "inboxes": 0, "domains": 0, "keys": 0, "webhooks": 0 },
  "created_at": "2026-11-18T10:00:00Z"
}
```

Then make a key inside the pod and hand it to that customer's agent:

```bash
curl -X POST https://api.trotta.email/v1/keys \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind agent", "pod_id": "pod_7hc2mxq4"}'
```

The answer carries the key once. Everything that key creates lands in the pod by itself: inboxes, domains, keys and webhooks. The same three steps in TypeScript:

```typescript
import { TrottaMail } from "trotta-mail";

// A key outside every pod: your platform's own.
const platform = new TrottaMail({ apiKey: process.env.TROTTA_MAIL_API_KEY });

const pod = await platform.pods.create({ name: "Northwind", clientId: "northwind" });
const { key } = await platform.keys.create({ name: "Northwind agent", podId: pod.id });

// The customer's agent works with the pod key. Every other pod answers 404.
const northwind = new TrottaMail({ apiKey: key });
const inbox = await northwind.inboxes.create({ name: "northwind-support", clientId: "support" });

console.log(inbox.address, inbox.pod_id); // northwind-support@trotta.email pod_7hc2mxq4
```

A `client_id` on an inbox is unique per pod, so every customer can have an inbox with the `client_id` `support`. For one agent with one address, a lighter tool exists: a key made with `inbox_id` reaches that one inbox and nothing else.

## What can a key in a pod see?

A key in a pod sees its own pod and nothing else, on every route.

- Every id outside the pod answers `404 not_found`, with exactly the body an unknown id gets. The key cannot tell another customer's inbox from one that does not exist.
- Lists, search, the held queue, `wait`, events, the event stream, the MCP tools and usage show the pod alone.
- A webhook it creates hears its own pod's mail and no other.
- It cannot create, rename or delete pods, create a human's mailbox, or read the audit trail, billing or members. Those answer `403 key_limited_to_pod`.

Try it with the pod key and the id of an inbox that belongs to another pod:

```bash
curl -i https://api.trotta.email/v1/inboxes/inb_7Qh2mXc4 \
  -H "Authorization: Bearer $NORTHWIND_POD_KEY"
# HTTP/2 404, error code not_found: the same answer an id that never existed gets
```

A human's mailbox never belongs to a pod. So a customer's agent cannot reach the mail of the humans on your own team, whatever it is told to do.

## How does the platform watch every tenant?

The platform watches every tenant with a key, or a human sign-in, that is outside every pod: those see every pod. `?pod_id=` cuts a list to one pod on `/v1/inboxes`, `/v1/threads`, `/v1/messages`, `/v1/keys`, `/v1/webhooks`, `/v1/domains` and `/v1/usage`.

```bash
curl "https://api.trotta.email/v1/threads?pod_id=pod_7hc2mxq4" \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY"
```

Every event carries a `pod_id`, so one platform webhook can route events by tenant. A webhook registered with a `pod_id` is sent that pod's events and no others.

Screening does not change inside a pod. Every message is checked before it is delivered, and mail the guard holds waits for a human. A pod key sees that a message is held and why, and nothing its sender wrote.

## Can each tenant have its own domain?

Each tenant can have its own domain on a paid plan. A domain in a pod is for that pod's inboxes: an inbox lives on the shared `trotta.email` domain or on a verified domain of its own pod. Inside a pod, another pod's domain answers as one nobody has.

A domain per tenant also helps keep sending reputation apart, because receiving mail servers weigh the domain that mail comes from. The DNS steps are in [custom domain email for agents](https://trotta.email/learn/custom-domain-email-for-agents).

## What limits apply across pods?

Plan limits are shared by the whole organization: every pod's inboxes, domains and webhooks count toward the one plan.

| Plan | Inboxes | Own domains | Webhooks |
| --- | --- | --- | --- |
| Free | 2 | None | 1 |
| Developer | 5 | Up to 3 | Unlimited |
| Startup | 50 | Up to 25 | Unlimited |
| Enterprise | Unlimited | Unlimited | Unlimited |

- `GET /v1/usage?pod_id=` returns one pod's own use, with the organization's limits beside it. That is the number to bill a customer from.
- A pod can be deleted once it is empty. Revoke its keys and delete its inboxes, domains and webhooks first, or the call answers `409 pod_not_empty`.
- Creating, renaming and deleting pods is written to the audit trail.
- Pods are managed by the owner and admins of the organization.

The [pods docs](https://trotta.email/docs/pods) cover each rule, and [plans and limits](https://trotta.email/docs/plans) has the full table. A team of agents inside one company can use the same walls: see [multi-agent teams](https://trotta.email/use-cases/multi-agent-teams).

## Questions

### Should each customer get a pod or one inbox?

A pod, when a customer has or may later have more than one inbox, or a domain, webhook or key of its own. For one agent with one address, an inbox and a key limited to that inbox is enough.

### Can a pod key read another pod's mail if it knows the id?

No. Every id outside its pod answers 404 not_found, with exactly the body an unknown id gets.

### Do pods count against the plan?

Plans count inboxes, domains and webhooks, not pods. Every pod's inboxes, domains and webhooks count toward the organization's one plan.

### Can each customer's agent connect over MCP?

Yes. A pod key works as the bearer token for the MCP server, and the tools show that pod alone. With an OAuth sign-in, a human picks the inboxes or the one pod an assistant may use.

### Can a human's mailbox go in a pod?

No. Pods hold agent inboxes, domains, keys and webhooks. A human's mailbox is read by the human it belongs to and never belongs to a pod.

## Related

- [Pods](https://trotta.email/docs/pods) Docs
- [Multi-agent teams](https://trotta.email/use-cases/multi-agent-teams) Use cases
- [Security model](https://trotta.email/docs/security) Docs
- [Plans and limits](https://trotta.email/docs/plans) Docs
- [How to put AI agent inboxes on your own domain](https://trotta.email/learn/custom-domain-email-for-agents) Guides
- [What an email API for AI agents must do](https://trotta.email/learn/email-api-for-ai-agents) Guides

Give your agent an inbox of its own. Free for two inboxes. No card.

[Get an inbox](https://trotta.email/signup) [Read the docs](https://trotta.email/docs)
