Pods

Most accounts never need one. If what you are building hands addresses to its own users — a tenant per landlord, per client, per customer — a pod is where each of them goes.

A pod holds addresses and domains, and it is a real boundary rather than a folder: mail sent from a pod lands on that pod's own sending reputation. So when one of your customers mails a thousand dead addresses, the bounces are theirs. Your other customers keep delivering.

That is the reason this product is on Amazon SES rather than anywhere cheaper, and it is the thing you cannot add afterwards — on a provider with one shared reputation, one careless user degrades delivery for everybody.

GET    /v1/pods                                              yours, the default first
POST   /v1/pods                                              make one
GET    /v1/pods/2f0f6a1c-9a4e-4e26-9a60-2b4c0f5e1d33          one of them
PATCH  /v1/pods/2f0f6a1c-9a4e-4e26-9a60-2b4c0f5e1d33          rename it, or change your own id for it

Making one, and putting addresses in it

POST /v1/pods
{ "name": "Acme Ltd", "client_id": "cus_8812" }

name is what a person reads. client_id is your id for this customer, carried and returned and never parsed by us — so your own system can look a pod up by the key it already has, instead of keeping a mapping table.

Then name the pod when you create their addresses:

POST /v1/identities
{ "address": "hello@yourdomain.com", "type": "agent", "pod_id": "2f0f6a1c-9a4e-4e26-9a60-2b4c0f5e1d33" }

Leave pod_id out and the address goes in your account's default pod, which every account has from the day it is created — including yours, right now, before you have ever thought about this. Nothing you have already built is in the wrong place.

GET /v1/identities?pod_id=… lists one pod's addresses, and every address you read carries the pod_id it is in.

A domain can be in several pods at once, so two of your customers sending from the same domain of yours are still isolated from each other — yourdomain.com does not have to be added twice.

Checking the isolation rather than trusting it

A claim about reputation that you cannot measure is a claim. GET /v1/metrics takes a pod_id, and answers for that pod alone:

GET /v1/metrics?pod_id=2f0f6a1c-9a4e-4e26-9a60-2b4c0f5e1d33&days=30

{
"data": {
  "pod": { "id": "2f0f6a1c-9a4e-4e26-9a60-2b4c0f5e1d33", "name": "Acme Ltd" },
  "reputation": { "sending": "enabled" },
  "outbound": { "sent": 1840, "delivered": 1792, "bounced": 41, "rejected": 0, "complained": 7, "delivery_rate": 0.9739 },
  "inbound": { "received": 612, "spam": 9 }
}
}

Put two pods' numbers side by side and the separation is the answer: one customer's bounce rate is theirs.

reputation.sending is the part nothing else can tell you.

• enabled — the provider is taking mail from this pod.
• paused — the provider has suspended this pod and nobody else, because of its own bounce or complaint rate. Mail from it queues and retries rather than failing outright, which is correct and is also why you would otherwise never find out. This is how you find out.
• unknown — we cannot say. A pod that has never sent has no reputation yet, which is the usual reason.

There is no delete

A pod holds mailboxes and the correspondence in them, so the verb that destroys hundreds at once is one we have deliberately not built. Renaming works. To offboard a customer, suspend their addresses — expiry and suspension keep the mail, so the record of what was said survives the relationship.

What a pod is not

It is not a permission boundary. No API key is scoped to a pod; a key reaches the addresses it has been granted, which is a separate ladder and the one to use when you want a credential that can only see one customer's mail. See Authentication.

It is not billed for. Addresses are what we meter. Free and Developer include a pod for every inbox they include — three and ten — Startup includes twenty-five, and Enterprise has no limit. Splitting the inboxes you already pay for across containers costs us nothing, and a platform counting its own customers against an invoice is the friction this feature exists to remove. See Limits.