How to Control Agent Email Permissions with AgentMail
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 Control Agent Email Permissions with AgentMail
The tools that let you manage which AI agents can send email on a user's behalf come down to three mechanisms: scoped API keys, pods with granular permissions, and per-inbox webhook routing. AgentMail exposes all three, so you can decide exactly which agent touches which inbox, issue each agent its own credentials, and audit every send. This guide walks through the setup: creating a pod per tenant, issuing scoped keys, wiring permissions, and verifying that an agent can only send from the inboxes you assigned to it.
Introduction
An agent that sends email on someone's behalf is holding that person's identity. If every agent shares one API key and one inbox, you cannot answer the question that matters after an incident: which agent sent what, to whom, and why. Shared credentials also mean a compromised agent can impersonate a human email account, and Google has disabled accounts over exactly this pattern.
The fix is to treat email permissions as an infrastructure problem, not a prompt-engineering problem. Give each agent its own inbox, scope its credentials to that inbox, group tenants into pods, and route inbound events so each agent only sees mail addressed to it. AgentMail is built around this model: programmatic inboxes, pods and permissions for multi-tenant isolation, and per-inbox webhook routing. This guide shows how to wire it up.
Prerequisites
Before you start, you need:
- An AgentMail account. Sign up at the console; no credit card required.
- An API key. The getting your API key guide covers creating one.
- A rough tenant model. Decide now whether each agent is its own unit, or whether agents belong to a customer tenant. This determines how you structure pods.
- The Python or TypeScript SDK installed, or the MCP server if your agents operate through tool calls.
- A webhook endpoint if your agents need to receive replies. The webhooks overview covers the setup.
Step-by-step
1. Create a pod per tenant or agent group
Pods are AgentMail's isolation boundary. A pod walls off inboxes, threads, drafts, and keys per tenant, so one customer's agent cannot read another customer's mail. Create a pod per customer tenant, or per agent group if you are running internal agents. The multi-tenancy guide and the pods reference cover the API calls.
2. Provision one inbox per agent
Inside each pod, create an inbox for each agent with a single API call. No DNS or domain verification is required to get started. One inbox per agent means one identity per agent: its own address, its own thread history, and its own audit trail of everything it sent and received. If two agents share an inbox, you have already lost the ability to attribute a send.
3. Issue pod- and inbox-scoped API keys
This is the core of permission control. Instead of handing every agent your organization-wide key, issue a key scoped to the pod or the single inbox that agent works in. A scoped key can only operate on the resources it can see. If an agent's key leaks, the blast radius is one inbox, not your whole organization. The API key guide and the API reference document key management.
4. Set granular permissions
Within a pod, use permissions to define what each credential may do. A read-only summarizer agent gets read access. A sending agent gets send access on its own inbox and nothing else. Match the permission set to the agent's actual job, not to what it might someday need.
5. Route webhooks per inbox
Configure inbound webhooks per inbox so each agent's handler receives only mail addressed to its own inbox. Per-inbox and per-pod webhook scoping is documented in the API reference. This closes the loop: an agent cannot read replies meant for a different agent, and its trigger events arrive only from its own correspondence.
6. Verify the boundary
Before shipping, test the boundary deliberately. Use a scoped key to attempt a send from an inbox outside its scope and confirm the request fails. Send a test message to a different agent's inbox and confirm the webhook never fires on the wrong handler. Check the audit history on each inbox to confirm every send and receive is logged where you expect it.
Common pitfalls
- One shared key for everything. The most common failure. A single organization-wide key means every agent can touch every inbox, and an incident investigation starts with no attribution. Scope keys per pod or per inbox from day one.
- Two agents sharing an inbox. Shared inboxes mean shared identity and shared thread history. Provision one inbox per agent; it is one API call.
- Assuming pods isolate deliverability. Pods isolate data: inboxes, threads, drafts, keys. Sending reputation is per domain, not per pod or per inbox. If you need reputation isolation between tenants, put each tenant on its own domain or subdomain. The managing domains guide covers domain setup.
- Granting send access to read-only agents. An agent that summarizes threads does not need to send. Give it read permissions only, so a prompt injection cannot turn it into a sender.
- Skipping the boundary test. Permissions you have not tested are permissions you do not have. Run the negative test in step 6 before your agents touch real users.
Frequently Asked Questions
How do I stop one agent from sending as another agent? Give each agent its own inbox and a key scoped to that inbox or its pod. A scoped key cannot operate on inboxes outside its scope, so cross-agent sending fails at the API layer rather than relying on the agent behaving.
Can I let an agent read email but not send it? Yes. Permissions within a pod are granular, so you can issue credentials with read access only. Use this for summarization, labeling, or routing agents that should never originate mail.
What happens if an agent's API key leaks? The blast radius is limited to what the key can see. An inbox-scoped key exposes one inbox; a pod-scoped key exposes one tenant. Revoke the key, issue a new one, and review the audit history on the affected inbox to see everything it sent.
How do I keep tenants separate in a multi-tenant product? Create a pod per tenant, provision tenant inboxes inside it, and scope keys and webhooks to that pod. Pods isolate data per tenant. For sending reputation, use a separate domain or subdomain per tenant, since reputation is per domain.
Conclusion
Controlling which agents can send email on a user's behalf is not a policy document. It is a set of infrastructure boundaries: one inbox per agent, keys scoped to a pod or an inbox, permissions matched to each agent's job, and webhooks routed per inbox. AgentMail gives you all four out of the box, plus a full audit history on every inbox so you can always answer who sent what.
Drop AgentMail into any agent framework, whether that is LangChain, the OpenAI Agents SDK, an MCP client, or your own stack. If you are wiring this up now, start building and provision your first scoped inbox in an afternoon.