Pods

What are Pods?

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.

The Hierarchy

Organization (Your Business)
    └── Pod (Your Customer A)
        ├── Inbox 1
        ├── Inbox 2
        └── Domain 1
    └── Pod (Your Customer B)
        ├── Inbox 3
        ├── Inbox 4
        └── Domain 2

Organization: Your company’s AgentMail account

• You have one organization that represents your business

Pod: Each of your customers

• Create one pod per customer/tenant in your system
• Pods provide complete isolation between your customers’ data
• All resources (inboxes, domains, threads, drafts) can be scoped to a pod

Inbox: Individual email accounts within a pod

• Your customers can have multiple inboxes within their pod
• It is on you to provision resources for each of your customers

Why Use Pods?

Multi-Tenancy

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.

How Pods Work

Pod Lifecycle

As a basis, here are a couple of logistical stuff that happens on the API side when you create resources.

• When you sign up, you are automatically created a Default Pod, and all resources created whether its Inboxes or Domains all are associated with this Default Pod.
• You cannot delete a Pod that has existing children resources. Make sure to delete any existing Inboxes or Domains before deleting a Pod.

What You Can Do With Pods

Creating Resources

You can create the following resources within a pod:

• Inboxes
• Domains

These resources are automatically associated with the pod and inherit its isolation guarantees.

Listing Resources

You can list the following resources scoped to a pod:

• Inboxes (GET /pods/{pod_id}/inboxes) - View all inboxes in a pod
• Threads (GET /pods/{pod_id}/threads) - View all email conversations across all inboxes in the pod
• Drafts (GET /pods/{pod_id}/drafts) - View all draft emails across all inboxes in the pod
• Domains (GET /pods/{pod_id}/domains) - View all custom domains in the pod

This gives you a unified view of all activity within a customer’s workspace, making it easy to build features like:

• “Show me all unread emails for Customer X” (use labels here too!)
• “List all threads across all of Customer Y’s team inboxes”
• “Display all pending drafts for Customer Z”

Important Considerations

Pod Deletion Constraints

This is a safety mechanism to prevent accidental data loss. Here’s the correct deletion sequence:

1
// This will FAIL if the pod has any resources
2
await client.pods.delete(podId);
3
4
// Correct approach: Clean up resources first
5
async function offboardCustomer(podId: string) {
6
  // 1. Delete all inboxes
7
  const inboxRes = await client.inboxes.list(podId);
8
  for (const inbox of inboxRes.inboxes) {
9
    await client.inboxes.delete(inbox.inbox_id);
10
  }
11
12
  // 2. Delete all domains
13
  const domainRes = await client.domains.list({ podId });
14
  for (const domain of domainRes.domains) {
15
    await client.domains.delete(domain.domain_id);
16
  }
17
18
  // 3. Now you can delete the pod
19
  await client.pods.delete(podId);
20
}

What’s NOT Isolated to a Pod:

• API keys (these are organization-level and can access any resources in any pod)

Common Patterns and Use Cases

Pattern 1: Multi-Tenant SaaS

Each company using your platform gets their own pod:

1
// Customer A's workspace
2
Pod: "Acme Corp"
3
├── Inbox: support@acme.com
4
├── Inbox: sales@acme.com
5
└── Domain: acme.com
6
7
// Customer B's workspace
8
Pod: "TechStart Inc"
9
├── Inbox: hello@techstart.io
10
├── Inbox: team@techstart.io
11
└── Domain: techstart.io

Pattern 2: Agency Client Management

Each client gets their own isolated pod:

1
// Client 1
2
Pod: "Client - Retail Co"
3
├── Inbox: info@retailco.com
4
└── Domain: retailco.com
5
6
// Client 2
7
Pod: "Client - FinTech"
8
├── Inbox: support@fintech.ai
9
└── Domain: fintech.ai

Pattern 3: AI Agent Platform

Each AI agent gets its own pod with dedicated email infrastructure:

1
// Agent 1: Customer Support Agent
2
Pod: "Support-Agent"
3
├── Inbox: support@mycompany.com
4
├── Inbox: help@mycompany.com
5
└── Inbox: tickets@mycompany.com
6
7
// Agent 2: Sales Outreach Agent
8
Pod: "Sales-Agent"
9
├── Inbox: sales@mycompany.com
10
├── Inbox: outreach@mycompany.com
11
└── Inbox: leads@mycompany.com
12
13
// Agent 3: Marketing Agent
14
Pod: "Marketing-Agent"
15
├── Inbox: newsletter@mycompany.com
16
├── Inbox: campaigns@mycompany.com
17
└── Inbox: events@mycompany.com

FAQ

Next Steps

• Learn about Inboxes and how to create email accounts within pods
• Explore Domains to set up custom email domains for your pods