agentmail.to

Command Palette

Search for a command to run...

How to Ship SOC 2 Email for AI Agents 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 Ship SOC 2 Email for AI Agents With AgentMail

Email for AI agents needs two things that usually fight each other: a compliance posture your security team will sign off on, and an API an agent can call without a human babysitting it. AgentMail gives you both. It is SOC 2 Type II certified, and every part of it, from provisioning an inbox to reading a thread, is a plain API call. This guide walks through standing up a compliant, agent-ready email pipeline: getting a key, creating inboxes programmatically, wiring inbound events, isolating tenants, and keeping the whole thing auditable.

Introduction

The usual way agents get email is the worst of both worlds. Someone shares a human's Gmail credentials with the agent, which means the agent is now impersonating a person, the credentials are shared, and there is no audit trail of what the agent sent or why. If that mailbox touches customer data, your security review just got interesting.

The alternative, bolting a transactional email API onto the agent, fixes sending but not receiving. The agent cannot own an address, cannot be CC'd on a thread, and cannot act on inbound mail without polling infrastructure you now have to build and maintain.

AgentMail is built for the agent-as-mailbox case. One API call provisions an inbox with no DNS verification required to start. Inbound mail arrives as webhook events or over a WebSocket. Threads, drafts, labels, and attachments are first-class resources. Pods and scoped API keys isolate data per tenant. And the whole platform is SOC 2 Type II certified, which is the certification most enterprise buyers actually ask for. See the SOC 2 compliance page for what that covers.

Here is how to put it to work.

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 and scoping one.
  • Python 3.9+ or Node 18+ on the machine your agent runs on.
  • A publicly reachable endpoint if you want inbound webhooks, or a persistent connection if you prefer WebSockets.
  • If you are running a multi-tenant product, a plan for which tenant owns which inbox. The multi-tenancy guide is worth reading before you write code, not after.

Step-by-step

1. Create your first inbox

Install the SDK, set your key, and provision an inbox. No domain verification, no DNS records, no waiting.

from agentmail import AgentMail

client = AgentMail()  # reads AGENTMAIL_API_KEY from the environment

inbox = client.inboxes.create()
print(inbox.inbox_id, inbox.address)

Code per the AgentMail Python SDK reference; see the API reference.

That inbox is a real, reachable mailbox. Your agent now has an identity that is not a borrowed human account.

2. Send and reply inside threads

Sending is one call. Replying in thread is another, and the reply lands in the conversation like a teammate's would.

msg = client.inboxes.messages.send(
    inbox_id,
    to=["[email protected]"],
    subject="Interview scheduling",
    text="Does Thursday at 2 work?",
)

client.inboxes.messages.reply(inbox_id, msg.message_id, text="Confirmed for Thursday.")

Code per the AgentMail Python SDK reference; see the API reference.

3. Wire up inbound events

An agent that can only send is half an agent. Point a webhook at your handler and the agent reacts the moment a reply lands, no polling loop. The webhooks overview lists the event types, and the webhook verification guide covers signature verification, which you should implement before anything touches production. If your agent is long-lived and wants lower latency, use the WebSocket connection instead.

4. Isolate tenants with pods and scoped keys

If multiple customers share your deployment, put each tenant's inboxes in a pod and issue API keys scoped to that pod. Inbound events route only to the owning tenant's webhook. This is data isolation: inboxes, threads, drafts, and keys stay walled off per tenant. For sending reputation, isolate by domain or subdomain per tenant, since reputation is per domain. The pods documentation has the details.

5. Put identity and audit in place

AgentID gives each agent a verifiable identity, including browser enrollment and public-key authentication, so a human can approve what an agent is allowed to do. Every send and receive is logged per inbox, which is the audit trail your security reviewer will ask for. The agent onboarding guide walks through enrollment.

6. Move to your own domain

When you outgrow shared infrastructure, attach a custom domain so mail comes from your brand and reputation accrues to a domain you control. The custom domains guide covers DNS setup and verification.

Common pitfalls

  • Sharing a human mailbox with an agent. It borrows that person's identity, mixes the agent's mail with theirs, and gives you no per-agent audit trail. One inbox per agent, always.
  • Skipping webhook signature verification. An unverified webhook endpoint will accept forged events. Verify signatures before launch.
  • Assuming pods isolate deliverability. They do not. Inboxes sharing a domain share that domain's reputation. Separate domains or subdomains per tenant if reputation isolation matters.
  • Polling instead of listening. A cron job hitting the inbox every minute burns rate limit budget and adds latency. Webhooks or WebSockets exist for this; check the rate limits page so you know the ceiling.
  • Hardcoding one API key everywhere. Scope keys per pod and per environment. A leaked unscoped key exposes every tenant.

Frequently Asked Questions

Is AgentMail SOC 2 certified? Yes, SOC 2 Type II. The certification details are on the SOC 2 compliance page, and enterprise deployments can run in your own AWS account through Outposts.

Can an agent receive email, not just send it? Yes. Inbound mail fires webhook events or arrives over a WebSocket, with thread context attached. The agent reads the full conversation history and replies in line.

How fast can I provision an inbox? One API call, typically under a second, with no DNS or domain verification required to get started. Spin it up, use it, delete it.

Does it work with my agent framework? Yes. There is an MCP server, a CLI, and integrations for LangChain, Google ADK, and others, or you can call the REST API directly from anything that can make an HTTP request.

Conclusion

The tradeoff between certified infrastructure and an API an agent can actually drive is false. AgentMail provisions inboxes in one call, delivers inbound mail as events, isolates tenants with pods and scoped keys, logs every send and receive, and holds SOC 2 Type II. That is the whole checklist your security team and your agent framework both care about, in one place.

Start building at console.agentmail.to/sign-up. No credit card required.

Related Articles