> ## Documentation Index
> Fetch the complete documentation index at: https://docs.12m.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Identities

> One handle on top, a pool of warmed mailboxes underneath. The unit of identity in 12m.

An identity is the thing your code talks to. It has a stable **handle**
(`alice.acme@inboxbase.ai`), a **tier** (which sets the daily send cap), and a
**pool of backing mailboxes** that we provision, warm up, and rotate
across on your behalf.

You never address an individual mailbox. You address the identity; we
pick the mailbox. This is the whole point — it's why your code doesn't
need to know which domain we registered last week or which mailbox
finished its warmup yesterday.

## The handle

The handle is in the URL of every send and read endpoint:

```
POST /v1/identities/alice.acme@inboxbase.ai/send
GET  /v1/identities/alice.acme@inboxbase.ai/conversations
GET  /v1/identities/alice.acme@inboxbase.ai/events
```

Two reasons it's in the path and not a header:

* **Multi-identity orgs are the default.** A company with three product
  lines has three identities. Putting the identity in the path makes it
  impossible to accidentally send from the wrong one.
* **Logs are readable.** You can grep `alice.acme@inboxbase.ai` in the
  request log and find exactly that identity's traffic.

The handle is not the address recipients see. Recipients see the
rotated mailbox we picked for that send (e.g.
`alice.chen@tryacme.com`). 12m's role is to make rotation invisible to
your code; the handle is the customer-facing stable identifier.

## What we run underneath

For each identity we provision a pool of mailboxes across a small set
of domains we register on your behalf. Pool size and the number of
domains scale with the tier. New mailboxes start at warmup stage 0 —
they can send a tiny number of emails per day — and we ramp them up
over weeks under a curve that mimics organic growth so the receiving
providers don't flag them as bulk.

Every send goes through a picker that looks at:

* **Daily cap remaining** per mailbox
* **Warmup stage** (newer mailboxes get less weight)
* **Health score** (declines on bounces, spam complaints, auth
  failures; below 20 the mailbox is excluded)
* **Recipient affinity** (once a recipient receives mail from mailbox
  X, future sends to that recipient go through X for thread continuity)

You can read which mailbox we picked for any given send — it's in the
`account` field of the send response. We surface it for transparency,
not because you need it. If you find yourself acting on it (pinning a
recipient, picking a mailbox manually), tell us — we may be missing a
primitive.

## Tiers

Tiers fix three things: the identity's daily send cap, the size of the
mailbox pool we maintain underneath it, and the price.

| Tier       | Daily cap | Mailboxes | Domains |
| ---------- | --------- | --------- | ------- |
| Starter    | 150       | 2         | 2       |
| Growth     | 300       | 4         | 2       |
| Scale      | 1,000     | 12        | 3       |
| Pro        | 5,000     | 55        | 6       |
| Business   | 10,000    | 110       | 10      |
| Elite      | 20,000    | 220       | 18      |
| Enterprise | Custom    | Custom    | Custom  |

Hitting the daily cap returns `429 cap_exceeded` from `/send`. Caps reset
at midnight UTC. The dashboard shows your current usage on a rolling
graph.

## Lifecycle

The honest version of an identity's life:

1. **Provisioning** — we register the domains, configure DKIM/SPF/DMARC,
   create the mailboxes, validate auth. You can't send yet.
2. **Initial warmup** — mailboxes begin at stage 0, capped at single-digit
   sends per day. Real cold outbound runs at low volume from the highest-
   stage mailboxes.
3. **Steady state** — most mailboxes at stage 100, some still ramping.
   The picker spreads load and the rotation keeps any one mailbox from
   carrying disproportionate traffic.
4. **Repair** — a mailbox develops issues (bounces spike, reputation
   dip). We pull it out of rotation, reassign its pinned recipients to
   healthy siblings, and either rehab or replace.

Steps 2–4 happen continuously without your involvement. The dashboard
shows pool health if you want to look. Most teams don't.

## Cross-identity isolation

An identity's events, conversations, and rate limits are completely
separate from other identities in the same org. A reply to a conv on
identity A never appears on identity B's stream. The org-scoped API
key authorizes acting as any identity; the URL says which one.

<Note>
  If you need stricter isolation than "same key, different paths" — say,
  one team should only access identity A and another only identity B —
  that's on the roadmap as scoped keys. Today the right shape is one
  org per isolated tenant.
</Note>