Multi-tenant agent inboxes: one isolated workspace per customer
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
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.
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"}'{
"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:
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:
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_7hc2mxq4A 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:
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 getsA 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.
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.
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 cover each rule, and plans and limits has the full table. A team of agents inside one company can use the same walls: see 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.