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 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.
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
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_foundwith 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.
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.