Pods are an isolated abstraction that sits between your organization and your inboxes, providing a method to segment and organize email infrastructure for multi-tenant applications. If you’re building a service that offers email functionality to your customers, pods are your key to ensure customer resource isolation.
Organization: Your company’s AgentMail account
Pod: Each of your customers
Inbox: Individual email accounts within a pod
Pods enable you to offer AgentMail’s email infrastructure to your own customers while maintaining strict data isolation. Here’s how our customers use pods:
SaaS/Agency Platforms: Create a pod for each customer account. Each customer gets their own isolated email workspace.
White-Label Email: Offer email services under your own brand. Each end-user gets their own pod with complete data isolation.
AI Agent Platforms: Give each AI agent with its own purpose its own pod with dedicated inboxes and domains.
As a basis, here are a couple of logistical stuff that happens on the API side when you create resources.
Default Pod, and all resources created whether its Inboxes or Domains all are associated with this Default Pod.Pod that has existing children resources. Make sure to delete any existing Inboxes or Domains before deleting a Pod.You can create the following resources within a pod:
NOTE: as of now domains can only be either scoped to one pod, or all pods. I.E it is not possible to create a domain scoped to more than one but not all pods.
TIP: specify a client_id when creating a Pod so that you can decide how to
uniquely identify pods. That way you don’t need to create a table mapping your
organization_id’s for your customers or segment of your business to our
pod_id’s you can just set the client_id as your internal id so you can
access the resource using a unique identifier determined by you!
These resources are automatically associated with the pod and inherit its isolation guarantees.
You can list the following resources scoped to a pod:
GET /pods/{pod_id}/inboxes) - View all inboxes in a podGET /pods/{pod_id}/threads) - View all email conversations across all inboxes in the podGET /pods/{pod_id}/drafts) - View all draft emails across all inboxes in the podGET /pods/{pod_id}/domains) - View all custom domains in the podThis gives you a unified view of all activity within a customer’s workspace, making it easy to build features like:
Copy one of the blocks below into Cursor or Claude for complete Pods API knowledge in one shot.
Critical: You cannot delete a pod that has resources still attached to it. You must delete all inboxes and domains within the pod before you can delete the pod itself.
This is a safety mechanism to prevent accidental data loss. Here’s the correct deletion sequence:
When you delete an inbox or domain, all associated data (messages, threads, drafts) is automatically cleaned up. You don’t need to manually delete individual threads or messages.
What’s NOT Isolated to a Pod:
Each company using your platform gets their own pod:
Each client gets their own isolated pod:
Each AI agent gets its own pod with dedicated email infrastructure:
Yes! Inboxes in different pods can send and receive emails from each other just like any other email addresses. Pods only provide organizational isolation, not network isolation.
No, inboxes cannot be moved between pods. You will need to create a new inbox in the pod you want.
There’s no hard limit on the number of pods. You can create as many as you need for your customers.
Pods are optional but highly recommended for multi-tenant applications. If you’re only managing email for your own organization, you can work directly with inboxes without creating pods.
Yes! You can create pod-scoped API keys that are restricted to a single pod, or inbox-scoped API keys that are restricted to a single inbox within a pod. See the Multi-Tenancy guide for details on provisioning scoped keys.