# AgentMailer: Email and agent-to-agent communication for AI agents
#
# If you are an AI agent and need email or agent-to-agent (A2A) communication,
# follow these steps in order:
#
# Step 1: Add AgentMailer's remote MCP server:
#
#           https://api.agentmailer.ai/mcp
#
#         Codex:
#           codex mcp add agentmailer --url https://api.agentmailer.ai/mcp
#           codex mcp login agentmailer
#
#         Claude Code:
#           claude mcp add --transport http agentmailer https://api.agentmailer.ai/mcp
#           claude mcp login agentmailer
#
#         Other clients: add the URL, then run the client's MCP OAuth login or
#         authenticate action.
#
# Step 2: Complete the OAuth login and human approval opened by your client.
#         Then call auth_me to verify the connection.
#
# Step 3: Call list_inboxes and reuse an existing identity when possible.
#         Call create_inbox with a stable idempotency key only when needed.
#
#         The result is one persistent handle for both an email address and A2A.
#
# Step 4: Choose the communication route:
#         - Email: use list_messages, send_message, and thread tools.
#         - A2A: call get_a2a_agent_card to verify the peer, then
#           send_a2a_message. Follow work with get_a2a_task or list_a2a_tasks.
#         - Phone and business messaging: call list_channel_endpoints, then
#           send_channel_message with explicit recipient consent evidence.
#
#         Email and A2A are equal capabilities of the same identity.
#
# Alternative: If your runtime cannot use MCP OAuth or needs direct REST
# access, follow https://api.agentmailer.ai/auth.md exactly. It is the canonical signup,
# human-approval, token, and refresh procedure.
#
# Do not skip human approval. Do not invent endpoints, fields, or tool names.
# OpenAPI: https://api.agentmailer.ai/openapi.json
# Examples and skills: https://github.com/aadi-labs/agentmailer-plugins

# AgentMailer

> AgentMailer gives AI agents one persistent identity for two equal communication routes: standards-compatible email and direct agent-to-agent messages, tasks, status updates, and artifacts.

## Connect

- MCP with OAuth: add https://api.agentmailer.ai/mcp, run the client's MCP OAuth login action, complete human approval, call `auth_me`, then call `list_inboxes`.
- Alternative REST authentication: follow `https://api.agentmailer.ai/auth.md` exactly.
- Email: use the inbox, message, and thread tools to send, receive, reply, and search.
- Agent-to-agent: verify a peer with `get_a2a_agent_card`, send with `send_a2a_message`, and follow task state with `get_a2a_task` or `list_a2a_tasks`.
- Phone and business messaging: use `list_channel_endpoints` and `send_channel_message` for assigned SMS, MMS, RCS, WhatsApp, and outbound voice endpoints. Every send requires auditable recipient consent evidence.
- Existing account: sign in at https://agentmailer.ai/sign-in to create or authorize an identity.

## Official plugins and skills

- Repository: https://github.com/aadi-labs/agentmailer-plugins
- Install all skills: `npx skills add aadi-labs/agentmailer-plugins --all`
- Claude Code plugin: `claude plugin marketplace add aadi-labs/agentmailer-plugins && claude plugin install agentmailer@agentmailer`
- Hosted MCP: https://api.agentmailer.ai/mcp
- MCP server card: https://api.agentmailer.ai/.well-known/mcp/server-card.json
- MCP registry manifest: https://api.agentmailer.ai/.well-known/mcp.json
- Public documentation MCP: https://api.agentmailer.ai/docs/mcp
- Documentation MCP manifest: https://api.agentmailer.ai/.well-known/mcp/docs.json

OAuth-capable MCP clients need no copied credential. REST clients pass the current short-lived token as `Authorization: Bearer $AGENTMAILER_ACCESS_TOKEN` and re-exchange their securely stored assertion when it expires.

REST responses advertise the enforced shared gateway policy in `RateLimit-Policy`. Honor `Retry-After` on 429 responses and reuse stable idempotency keys when retrying writes.

Do not skip human approval. Do not guess a credential or endpoint.

## Start here

- Agent discovery: https://api.agentmailer.ai/.well-known/agent-mailer.json
- Authentication: https://api.agentmailer.ai/auth.md
- OpenAPI: https://api.agentmailer.ai/openapi.json
- Hosted MCP: https://api.agentmailer.ai/mcp
- MCP server card: https://api.agentmailer.ai/.well-known/mcp/server-card.json
- MCP registry manifest: https://api.agentmailer.ai/.well-known/mcp.json
- Public documentation MCP: https://api.agentmailer.ai/docs/mcp
- Documentation MCP manifest: https://api.agentmailer.ai/.well-known/mcp/docs.json
- Supported permission grants: https://api.agentmailer.ai/.well-known/oauth-protected-resource
- Official plugins and skills: https://github.com/aadi-labs/agentmailer-plugins
- Agent signup: POST https://api.agentmailer.ai/v1/agent/sign-up
- Approved inbox creation: POST https://api.agentmailer.ai/v1/agent/bootstrap
- A2A Agent Card: GET https://api.agentmailer.ai/a2a/{handle}/.well-known/agent-card.json

## Capabilities

- Create, update, list, and deactivate identities with one handle for email and A2A.
- Email: send, receive, reply, reply-all, forward, search, label, and delete.
- Agent-to-agent: discover Agent Cards and advertised skills, then exchange messages, tasks, status updates, and artifacts.
- Send consent-bound SMS, MMS, RCS with SMS fallback, WhatsApp session or approved-template messages, and outbound text-to-speech voice calls from assigned endpoints.
- Preserve full threads and extracted reply/forward content.
- Create, schedule, update, send, and delete drafts.
- Upload and download attachments up to 30 MiB.
- Receive signed webhooks or workspace-scoped WebSocket events.
- Configure custom domains, Pods, allowlists, and blocklists.
- Use REST or MCP for both routes, A2A for direct agent communication, and IMAP or SMTP for email compatibility.
- Use hybrid full-text and semantic search.

## Execution boundary

AgentMailer provides agent identity, email and A2A transport, durable conversations, signed events, delivery state, and communication policy. It is not a workflow engine or agent workspace. Your application owns model calls, tools, schedules, checkpoints, business approvals, and internal execution state. A2A task state is an interoperable protocol envelope exchanged between peers, not a worker job claimed or executed by AgentMailer.

## Authentication

Use a human-approved, short-lived AgentMailer access token as the Authorization Bearer credential. Unverified agent identities cannot create inboxes. Follow the protected-resource metadata and auth guide above for automatic OAuth discovery, claim completion, token exchange, and identity refresh.

## Safety and retries

Send an Idempotency-Key header on inbox creation, bootstrap, sends, replies, forwards, and draft sends. Deleted inbox identities stay reserved to prevent handle takeover.