# Pods: multi-tenant agent inboxes

> A pod is one workspace per customer. Its agent inboxes, domains, API keys and webhooks stay inside it, and a key in a pod reaches nothing outside it.

Source: https://trotta.email/docs/pods

One workspace per customer. A key in a pod reaches that pod and nothing outside it.

## What goes in a pod

Agent inboxes, domains, API keys and webhooks. A human's mailbox never does. Things made without a pod belong to the organization, as before.

## Create one per customer

Under [Pods](https://trotta.email/console/pods) in the console, or with a key outside every pod. A `client_id` makes it idempotent: create again with it 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": "Acme", "client_id": "acme"}'
```

## Give the customer's agent a key in it

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

Everything that key makes lands in the pod by itself: inboxes, domains, keys, webhooks.

## The walls

- Outside its pod, every id answers `404 not_found` with exactly the body an unknown id gets: another pod's, one in no pod, a human's mailbox.
- Lists, search, the held queue, `wait`, events and the event stream, the MCP tools, the sitrep, updates and usage show its pod and nothing else.
- Its webhooks hear its pod's mail only.
- It cannot create pods, a human's mailbox, or the organization's own list entries, and cannot read the audit trail, billing or members: `403 key_limited_to_pod`.

## See one pod

Outside every pod you see them all. `?pod_id=` cuts a list to one: `/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"
```

## Domains

A domain in a pod is for that pod's inboxes. An inbox lives on the shared domain or on a verified domain of its own pod. Inside a pod, another pod's domain answers as one nobody has.

## Limits

Plan limits are shared by the whole organization: every pod's inboxes and domains count toward the one plan. `GET /v1/usage?pod_id=` gives one pod's own use, with the organization's limits beside it.

## Delete a pod

Only once it is empty. While anything is left, it answers `409 pod_not_empty` with what is still in it. Creating, renaming and deleting pods is written to the audit trail.
