How AgentMail is architected

See how inboxes own messages, threads, and drafts, then learn the advanced pod and API key scope rules.

AgentMail centers on inboxes. Create an inbox, then send, receive, read, and organize the messages, threads, and drafts it owns. Start with the Quickstart if you have not created an inbox yet.

Start with an inbox

An inbox is an email address. Every message, thread, and draft belongs to exactly one inbox.

Inbox                         an email address
├── Messages                  individual emails
├── Threads                   grouped conversations
└── Drafts                    unsent messages

Use an inbox when you send or receive email. It is the resource your application reads from and writes to.

Use the supporting primitives

Primitive	What it is	What it belongs to
Domain	A sending and receiving domain you own and verify	Pod
API key	A credential scoped to an organization, pod, or inbox	Organization, pod, or inbox
Webhook	An HTTP endpoint AgentMail calls on events	Organization, pod, or inbox
WebSocket	A live connection that streams events for inboxes within the key’s scope	The level your key is scoped to
Label	A tag on messages and threads. AgentMail manages system labels such as `sent`, `received`, and `bounced`.	Inbox
List	An allow or block list of addresses or domains for sending, receiving, or replying	Organization, pod, or inbox

Advanced: pods and key scope

An organization is your account. It can contain pods, and each pod contains inboxes. Use pods when your product needs isolated inboxes for separate customers or tenants.

Organization
└── Pod
    └── Inbox

Most integrations use a pod-scoped key. The key selects its pod automatically, so inbox requests do not include a pod in the path. An organization-scoped key can access multiple pods and must name the target pod for pod-level resources, for example /v0/pods/{pod_id}/inboxes. Request paths never include an organization segment because the key identifies the organization.

Key scope	Pod in the path?
Pod or inbox	No. The key resolves the pod.
Organization	Yes, for pod-level resources.

If you replace a pod-scoped key with an organization-scoped key, update the request path to include the pod. Do the reverse when changing to a pod- or inbox-scoped key.

Check a key’s scope

Run the CLI command below to inspect the current key’s scope.

agentmail auth me

Use curl when the CLI is unavailable.

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

Sample response

{
  "scope_type": "pod",
  "scope_id": "<pod_id>",
  "organization_id": "<organization_id>",
  "pod_id": "<pod_id>",
  "api_key_id": "<api_key_id>"
}

scope_type names the key’s level (organization, pod, or inbox) and scope_id is the ID at that level. organization_id is always present; pod_id appears for pod- and inbox-scoped keys, and inbox_id (the inbox email address) only for inbox-scoped keys. api_key_id is present when authentication used an API key and absent for JWT and proxy credentials.

How AgentMail is architected

Start with an inbox

Use the supporting primitives

Advanced: pods and key scope

Check a key’s scope

On this page