# Pods

> Put each of your customers in a Pidgeon pod: their addresses, their domains and their own sending reputation, so one customer’s bounces cannot reach another’s delivery.

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.

```text
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

```json
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:

```json
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:

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

```json
{
"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](https://pidgeon.ai/docs/authentication.md).

**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](https://pidgeon.ai/docs/limits.md).