Documentation

AgentInbox is an MCP server that gives AI agents their own email addresses. Connect it to Claude Code, Codex, Cursor, or any MCP-compatible client.

Quick start

Add the AgentInbox MCP server to your client in one command:

claude mcp add --transport http agentinbox https://mcp.agentinbox.sh/mcp

Or add it manually to your MCP config:

{
  "mcpServers": {
    "agentinbox": {
      "url": "https://mcp.agentinbox.sh/mcp"
    }
  }
}

If you have an API key, pass it as a header:

{
  "mcpServers": {
    "agentinbox": {
      "url": "https://mcp.agentinbox.sh/mcp",
      "headers": {
        "Authorization": "Bearer sk-your-api-key"
      }
    }
  }
}

Authentication

AgentInbox supports two authentication methods. Both give your agent a persistent identity and email address.

Option A: OAuth auto-approve (recommended)

MCP clients like Claude Code, Codex, and Cursor handle this automatically. On first connect, a browser tab opens briefly and closes — that's it. Your agent gets a permanent identity.

Agent connects to mcp.agentinbox.sh/mcp
Server responds 401 — client discovers OAuth endpoints
Client auto-registers via Dynamic Client Registration
Browser opens /authorize — auto-approves instantly, redirects back
Client exchanges code for access token — stored locally
Agent auto-assigned a unique email address
On reconnect: client reuses stored credentials — fully automatic

Option B: API key

Pass a Bearer token in your MCP config. One-time setup, then fully automatic forever. No browser needed.

"headers": { "Authorization": "Bearer sk-your-api-key" }

How agent identity works

Your agent's identity is tied to its OAuth client_id or API key. Same credentials = same agent = same email address. No agentId parameter needed — the server knows who you are from your token.

Tools reference

The AgentInbox MCP server exposes 3 tools. Identity is derived from your auth token — no agent ID needed in any call.

send_email

Send an email from your inbox. Supports plain text and HTML, with threading via inReplyTo.

Parameter	Type	Required	Description
to	email	yes	Recipient email address
subject	string	yes	Email subject line
body	string	yes	Email body (plain text)
htmlBody	string	no	Optional HTML body
inReplyTo	string	no	Message-ID to reply to (enables threading)

Returns: emailId, messageId, threadId, status, from, to, subject

Request

{
  "to": "user@example.com",
  "subject": "Hello from my agent",
  "body": "This email was sent by an AI agent."
}

Response

{
  "emailId": "22222222-...",
  "messageId": "22222222-...@agent-mail.agentinbox.sh",
  "threadId": "22222222-...",
  "status": "sent",
  "from": "agent-b4a0@agent-mail.agentinbox.sh",
  "to": "user@example.com",
  "subject": "Hello from my agent"
}

get_emails

Retrieve emails from your inbox with optional filtering by direction or thread.

Parameter	Type	Required	Description
limit	number	no	Max emails to return (default: 10)
direction	"inbound" \| "outbound"	no	Filter by email direction
threadId	uuid	no	Filter by conversation thread

Returns: emails[], total

Request

{
  "limit": 5,
  "direction": "inbound"
}

Response

{
  "emails": [
    {
      "id": "...",
      "from": "user@example.com",
      "to": "agent-b4a0@agent-mail.agentinbox.sh",
      "subject": "Help with my order",
      "body": "...",
      "direction": "inbound",
      "status": "received",
      "created_at": "2026-03-06T..."
    }
  ],
  "total": 1
}

get_inbox_address

Get your agent's email address and account details.

No parameters required.

Returns: email, displayName, plan, domain

Request

{}

Response

{
  "email": "agent-b4a0@agent-mail.agentinbox.sh",
  "displayName": "agent-b4a0",
  "plan": "free",
  "domain": "agent-mail.agentinbox.sh"
}

Plans & rate limits

Each agent is assigned a plan tier that determines email throughput.

Plan	Price	Emails	Burst limit
Free	Free	500 / month	10 / hour
Pro	$5 / month	10,000 / month	100 / hour

Email flow

Outbound (agent sends)

Agent calls send_email tool
MCP server constructs raw MIME email with headers
Email sent via AWS SES SendRawEmail
Email record stored in database with message ID and thread ID

Inbound (agent receives)

Email arrives at *@agent-mail.agentinbox.sh
AWS SES stores raw email in S3, triggers Lambda
Lambda parses headers, body, and threading info
Email stored in database; agent retrieves via get_emails

Threading

Emails are grouped into threads using In-Reply-To and References headers. Pass inReplyTo when sending a reply to maintain the conversation thread. Use threadId in get_emails to fetch all messages in a thread.

← Back to home