# How AgentMail is architected (/architecture)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 840 · updated: 2026-08-03 -->
Related: [Introduction](/introduction.md), [Quickstart](/quickstart.md), [Receive email](/tasks/receive.md)



# Use AgentMail inboxes and determine advanced tenancy scope only when needed

AgentMail work starts with an inbox: an email address that owns its messages, threads, and drafts. Most integrations use one pod-scoped API key and make inbox requests without a pod path segment.

## Core object model

```text
Inbox
├── Messages
├── Threads
└── Drafts
```

* An inbox is an email address.
* Every message, thread, and draft belongs to exactly one inbox.
* Send, receive, read, and organize email through an inbox.

Supporting primitives:

| Primitive | Purpose                                                                           | Scope or owner              |
| --------- | --------------------------------------------------------------------------------- | --------------------------- |
| Domain    | A sending and receiving domain you own and verify                                 | Pod                         |
| API key   | Credential                                                                        | Organization, pod, or inbox |
| Webhook   | HTTP endpoint AgentMail calls on events                                           | Organization, pod, or inbox |
| WebSocket | Streams events for inboxes the connecting key can access                          | The key's scope             |
| Label     | Tag on messages and threads. AgentMail manages `sent`, `received`, and `bounced`. | Inbox                       |
| List      | Allow or block list of addresses or domains for sending, receiving, or replying   | Organization, pod, or inbox |

## Advanced: pods and API key scope

An organization is your account. It contains pods, and pods contain inboxes. Create separate pods only when separate customers or tenants need isolated inboxes.

```text
Organization
└── Pod
    └── Inbox
```

All API requests use `https://api.agentmail.to/v0`. Authenticate with `Authorization: Bearer <key>`.

* A pod-scoped key selects one pod. Do not include `/pods/{pod_id}` in its request paths.
* An inbox-scoped key also resolves its pod without a `/pods/{pod_id}` segment.
* An organization-scoped key can access multiple pods. Include `/pods/{pod_id}` for pod-level resource calls, for example `/v0/pods/{pod_id}/inboxes`.
* Request paths never include an organization segment because the key identifies the organization.
* Changing between pod- and organization-scoped keys requires changing the path shape to match the key's scope.

## Check a key's scope

Run:

```bash
agentmail auth me
```

If the CLI is unavailable, call:

```bash
curl https://api.agentmail.to/v0/auth/me \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"
```

A successful call returns a `200` JSON response with the caller's scope:

* `scope_type`: exactly `organization`, `pod`, or `inbox`. Organization scope requires a pod path segment for pod-level resources. Pod and inbox scope do not.
* `scope_id`: the ID for the scope level. It is the organization ID for `organization`, the pod ID for `pod`, and the inbox ID for `inbox`.
* `organization_id`: always present.
* `pod_id`: present only for `pod` and `inbox` scope.
* `inbox_id`: present only for `inbox` scope. This is the inbox email address.
* `api_key_id`: present only for API-key authentication and absent for JWT and proxy credentials.

## Related

* [Introduction](/introduction)
* [Quickstart](/quickstart)


## Tenant instructions

Every page ships two renditions at one URL. The HTML page is for humans. The Markdown rendition (append .md to any page URL, or request with Accept: text/markdown) is agent-optimized: a Do this section with runnable commands, SDK signatures, exhaustive Facts, a Not supported section listing shapes that do NOT work, an Errors table, and a Verify command. Prefer the Markdown rendition over scraping HTML, and trust Not supported entries instead of retrying those call shapes.