agentmail.to

Command Palette

Search for a command to run...

How to Isolate Every Tenant's Inbox with AgentMail

Last updated: 11/17/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.

How to Isolate Every Tenant's Inbox with AgentMail

Multi-tenant AI products live or die on tenant boundaries. When every customer's agent needs its own email identity, the boundary has to hold at the inbox level: one tenant's mail, threads, drafts, and credentials must never be reachable from another tenant's context. AgentMail gives you that boundary with pods, per-tenant inboxes, and scoped API keys, provisioned through a single API call per inbox. This guide walks through the full setup: prerequisites, the step-by-step build, and the mistakes that leak tenant data in production.

Introduction

The default approach most teams reach for is one shared mailbox with tenant IDs in the subject line. That works until it does not. A shared inbox means a shared identity, replies from different tenants colliding in one thread view, and no way to hand one customer's agent only that customer's mail. It also means one customer's sending behavior puts every other customer's deliverability at risk, because sending reputation lives at the domain level.

The alternative is real isolation: each tenant gets its own inbox, its own webhook routing, and its own API credentials. AgentMail is built for exactly this shape. Inboxes are provisioned programmatically in a single API call with no DNS verification required to get started, and pods wall off data per tenant. The rest of this guide shows how to put the pieces together.

Prerequisites

Before you start, you need:

  • An AgentMail account and API key. Get one from the console; the getting-started guide covers key creation.
  • A tenant model in your own system: a stable tenant ID you control, which you will map to AgentMail resources.
  • A webhook endpoint per tenant, or a single endpoint that can route by inbox. Inbound mail arrives as webhook events, so your handler needs to know which tenant a delivery belongs to before it touches the payload.
  • A plan for volume. The free tier includes 3 inboxes and 3,000 messages, the Developer plan covers 10 inboxes at $20/month, and the Startup plan caps at 150 inboxes with $2 per inbox overage. Past roughly 150 inboxes, Enterprise pricing is the right conversation rather than extrapolating Startup-tier math.
  • If you are building in an agent framework, the LangChain integration or the MCP server saves you writing the tool wrappers yourself.

Step-by-step

1. Create a pod per tenant

Pods are AgentMail's tenancy primitive. A pod isolates data: inboxes, threads, drafts, and API keys created inside a pod are scoped to that pod and not visible from outside it. Create one pod per customer tenant, keyed by your own tenant ID so the mapping is deterministic.

The multi-tenancy guide and the pods reference cover the API calls. The pattern is simple: on tenant signup, create a pod named after the tenant ID, store the mapping, and treat the pod as the tenant's email boundary from then on.

2. Provision one inbox per agent inside the pod

With the pod in place, create inboxes inside it. One API call provisions an inbox, no DNS or domain verification required, so you can do this lazily the first time a tenant's agent needs an address rather than pre-provisioning. The inboxes docs show the call.

Decide the granularity deliberately: one inbox per tenant is the minimum, but one inbox per agent or per function (support, outreach, billing) inside the tenant's pod keeps threads and webhook routing cleaner as the product grows.

3. Scope API keys to the pod

Do not hand your tenants' runtime workloads a global key. Issue pod-scoped API keys so a compromised or misconfigured credential in one tenant's execution environment can only touch that tenant's pod. This is the credential half of isolation: even if your agent runtime is shared infrastructure, the keys it holds are not.

4. Route inbound mail per inbox

Set up webhooks so deliveries for a tenant's inbox reach that tenant's handler. Two workable shapes:

  • One webhook endpoint per tenant, configured when you provision the inbox. Simplest to reason about, and the tenant boundary is physical.
  • One shared endpoint that routes on the inbox ID in the event payload. Fewer endpoints to manage, but the routing logic in your handler becomes part of your isolation boundary, so test it like one.

Verify webhook signatures on every delivery. The webhook verification docs cover the signing scheme.

5. Separate domains where reputation matters

This is the step teams get wrong. Sending reputation is per domain, not per inbox. Inboxes sharing a domain share that domain's reputation, and pods do not change that: pods isolate data, not deliverability. If one tenant's agent sends aggressively and gets the domain flagged, every tenant on that domain feels it.

The fix is custom domains: give high-volume or reputation-sensitive tenants their own domain or subdomain. For a small pilot on a handful of tenants, a shared domain is fine. For a product where tenants send meaningful volume, plan the domain-per-tenant (or per-tier) model early, because retrofitting it after a deliverability incident is painful.

6. Verify the boundary before launch

Write an isolation test suite and run it in CI:

  • A key scoped to tenant A's pod cannot list or read tenant B's inboxes, threads, or drafts.
  • A webhook for tenant B's inbox never reaches tenant A's handler.
  • Sending from tenant A's inbox never appears in tenant B's thread history.
  • Deleting a tenant tears down its pod cleanly, with no orphaned inboxes or keys.

If any of these fail, the bug is in your mapping or routing layer, not in the isolation model. Fix it before the first paying customer, not after.

Common pitfalls

  • Subject-line tenancy in a shared inbox. Parsing tenant IDs out of subjects breaks the first time a customer forwards mail or a reply chain forks. One inbox per tenant removes the parsing entirely.
  • Assuming pods isolate deliverability. They do not. Pods isolate data; reputation follows the domain. Pair pods with per-tenant domains where sending volume matters.
  • Global API keys in shared runtimes. A global key turns one tenant's compromised container into every tenant's problem. Pod-scoped keys cap the blast radius.
  • Unverified webhooks. An unsigned webhook endpoint accepts forged deliveries. Verify signatures on every event.
  • Provisioning inboxes at signup with no cleanup. Trial tenants churn. If you pre-provision inboxes and never tear down pods, you pay for inboxes nobody uses. Provision lazily and delete pods on tenant offboarding.

Frequently Asked Questions

What does a pod actually isolate? Data: inboxes, threads, drafts, and API keys scoped to the pod are not visible from outside it. It does not isolate sending reputation, which is per domain. For reputation isolation between tenants, use separate domains or subdomains.

Do I need one domain per tenant? Not always. On a shared domain, tenants share that domain's reputation. If tenants send low volume, a shared domain is fine. If tenants send meaningful volume, or one tenant's behavior could put others at risk, give them their own domain or subdomain.

How do inbound emails reach the right tenant's agent? Webhooks. Configure a webhook per inbox, either one endpoint per tenant or a shared endpoint that routes on the inbox ID. Verify the signature on every delivery before processing the payload.

What happens when a tenant churns? Delete the tenant's pod. That removes its inboxes, threads, and scoped keys in one operation, which is why mapping every email resource to a pod at creation time matters.

Conclusion

Tenant isolation for agent email is not one feature, it is four decisions made together: a pod per tenant for data, scoped keys for credentials, per-inbox webhook routing for inbound mail, and per-tenant domains where sending reputation matters. AgentMail gives you the primitives for all four, and the inbox itself is one API call with no DNS setup to get started. The quickstart takes you from key to first inbox in minutes, and sign-up needs no credit card. Build the isolation test suite before launch, and the boundary will hold.

Related Articles