# Agent Mailbox - Complete Documentation for AI Agents & Agentic Systems

> Email infrastructure for AI agents and agentic systems. Send, receive, and manage emails programmatically.

Agent Mailbox by Compostable AI is a multi-tenant email platform purpose-built for AI agents, agentic systems, and autonomous AI workflows. It provides email capabilities through REST APIs, webhooks, and MCP (Model Context Protocol) tools for Claude Desktop, Claude Code, and other AI assistants.

## Free Tier for AI Agents

Agent Mailbox offers a generous free tier for AI agents to send and receive operational emails. Built for the reliable email delivery workflows that businesses need to trust - from transactional notifications to customer communications. No credit card required to get started.

## About

Agent Mailbox is a product by [Compostable AI](https://compostable.ai).

Agent Mailbox is available on the AWS Marketplace and Compostable AI is an AWS Technology and Services Partner.

## Quick Start

1. Sign up at https://signup.agentmail.compostable.ai
2. Verify your email and set a password
3. Create a tenant (organization) with a custom subdomain
4. Create mailboxes under your tenant
5. Use the API or MCP tools to send/receive emails

## APIs

### Mailbox API (System)
- **Base URL**: `https://api.agentmail.compostable.ai`
- **Auth**: HMAC-SHA256 signatures
- **Purpose**: Send emails, receive messages, manage attachments
- **Docs**: https://agentmailbox.to/apidocs/mailbox/

#### Mailbox API Endpoints

**Messages**
- `POST /api/v1/mailboxes/{mailbox_id}/messages` - Send an email
- `GET /api/v1/mailboxes/{mailbox_id}/messages` - List messages in mailbox
- `GET /api/v1/mailboxes/{mailbox_id}/messages/{message_id}` - Get message details
- `DELETE /api/v1/mailboxes/{mailbox_id}/messages/{message_id}` - Delete a message

**Attachments**
- `GET /api/v1/mailboxes/{mailbox_id}/messages/{message_id}/attachments` - List attachments
- `GET /api/v1/mailboxes/{mailbox_id}/messages/{message_id}/attachments/{attachment_id}` - Download attachment

**Delivery Tracking**
- `GET /api/v1/mailboxes/{mailbox_id}/messages/{message_id}/delivery-status` - Check delivery status

### My Tenant API (Portal)
- **Base URL**: `https://api.agentmail.compostable.ai`
- **Auth**: JWT or HMAC-SHA256
- **Purpose**: Manage domains, mailboxes, credentials, webhooks
- **Docs**: https://agentmailbox.to/apidocs/my-tenants/

#### My Tenant API Endpoints

**Tenant Management**
- `GET /api/v1/portal-api/my-tenants` - List your tenants
- `GET /api/v1/portal-api/my-tenants/{codename}` - Get tenant details
- `PATCH /api/v1/portal-api/my-tenants/{codename}` - Update tenant settings

**Mailbox Management**
- `POST /api/v1/portal-api/my-tenants/{codename}/mailboxes` - Create mailbox
- `GET /api/v1/portal-api/my-tenants/{codename}/mailboxes` - List mailboxes
- `GET /api/v1/portal-api/my-tenants/{codename}/mailboxes/{id}` - Get mailbox
- `PATCH /api/v1/portal-api/my-tenants/{codename}/mailboxes/{id}` - Update mailbox
- `DELETE /api/v1/portal-api/my-tenants/{codename}/mailboxes/{id}` - Delete mailbox

**API Credentials**
- `POST /api/v1/portal-api/my-tenants/{codename}/credentials` - Create API credentials
- `GET /api/v1/portal-api/my-tenants/{codename}/credentials` - List credentials
- `DELETE /api/v1/portal-api/my-tenants/{codename}/credentials/{id}` - Revoke credentials

**Webhooks**
- `POST /api/v1/portal-api/my-tenants/{codename}/webhooks` - Create webhook
- `GET /api/v1/portal-api/my-tenants/{codename}/webhooks` - List webhooks
- `GET /api/v1/portal-api/my-tenants/{codename}/webhooks/{id}` - Get webhook
- `PATCH /api/v1/portal-api/my-tenants/{codename}/webhooks/{id}` - Update webhook
- `DELETE /api/v1/portal-api/my-tenants/{codename}/webhooks/{id}` - Delete webhook
- `POST /api/v1/portal-api/my-tenants/{codename}/webhooks/{id}/rotate-secret` - Rotate webhook secret
- `GET /api/v1/portal-api/my-tenants/{codename}/webhooks/{id}/deliveries` - List delivery history

**Domain Management**
- `POST /api/v1/portal-api/my-tenants/{codename}/domains` - Add custom domain
- `GET /api/v1/portal-api/my-tenants/{codename}/domains` - List domains
- `DELETE /api/v1/portal-api/my-tenants/{codename}/domains/{id}` - Remove domain
- `POST /api/v1/portal-api/my-tenants/{codename}/domains/{id}/verify` - Verify domain DNS

## MCP Integration

Agent Mailbox provides MCP (Model Context Protocol) servers for AI agents like Claude Desktop and Claude Code.

### Available MCP Tools

**Email Operations**
- `send_email` - Send emails with HTML/text body and attachments
- `list_emails` - List inbox messages with filtering and pagination
- `read_email` - Read full email content including attachments
- `track_email` - Check delivery status (sent, delivered, bounced, etc.)

**Mailbox Management**
- `create_mailbox` - Create a new mailbox under your tenant
- `list_mailboxes` - List all mailboxes in your tenant
- `get_mailbox` - Get mailbox details

### MCP Server URLs
- **User MCP**: For email operations (send, receive, read)
- **Admin MCP**: For tenant management operations

### Compatible AI Assistants & Agents

Agent Mailbox works with any AI assistant or agentic system that supports MCP or REST APIs:

**MCP-Compatible (Native Integration)**
- Claude Desktop (Anthropic)
- Claude Code / Claude CLI (Anthropic)
- Cursor (AI code editor)
- Windsurf (Codeium)
- Continue.dev
- Cline (VS Code)
- Zed Editor
- Any MCP-compatible client

**REST API Compatible (Universal)**
- ChatGPT / GPT-4 (OpenAI) - via function calling
- Gemini (Google) - via function calling
- GitHub Copilot
- Amazon Q Developer
- Replit Agent / Ghostwriter
- Perplexity AI
- Cohere Command
- Mistral AI
- Llama-based agents
- LangChain agents
- AutoGPT / AgentGPT
- CrewAI agents
- Custom autonomous agents

### MCP Configuration Example

```json
{
  "mcpServers": {
    "agentmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.agentmail.compostable.ai/tenant/{tenant}/mcp"],
      "env": {
        "MCP_REMOTE_CLIENT_ID": "<your-client-id>",
        "MCP_REMOTE_CLIENT_SECRET": "<your-value-here>"
      }
    }
  }
}
```

Docs: https://agentmailbox.to/apidocs/mcp/

## Authentication

### HMAC-SHA256 (API Keys)
For programmatic access. Generate API credentials in the portal.

Required headers:
- `X-Api-Key`: Your API key ID
- `X-Timestamp`: Unix timestamp (seconds since epoch)
- `X-Body-Hash`: Base64-encoded SHA256 hash of request body
- `X-Signature`: HMAC-SHA256 signature of the canonical request

Signature format:
```
{METHOD}\n{PATH}\n{QUERY}\n{BODY_HASH}\n{TIMESTAMP}
```

### OAuth2 (MCP)
For MCP servers. Supports:
- **Client Credentials flow (M2M)**: For automated systems
- **Authorization Code flow (Browser)**: For interactive users

Token endpoint: `https://auth.agentmail.compostable.ai/oauth2/token`

## Key Concepts

### Tenant
An organization with a custom subdomain (e.g., `mycompany.agentmail.compostable.ai`). Tenants have isolated mailboxes and credentials.

### Mailbox
An email address under a tenant's domain. Each mailbox can have its own API credentials with scoped permissions.

### Credentials & Permissions
- **admin**: Full access to all operations
- **sending_only**: Can only send emails
- **receiving_only**: Can only read/receive emails

### Webhooks
Real-time HTTP callbacks for email events. Configure webhooks at the tenant or mailbox level.

**Supported Events:**
- `email.delivered` - Email successfully delivered to recipient
- `email.bounced` - Email bounced (hard or soft bounce)
- `email.complained` - Recipient marked email as spam
- `email.opened` - Recipient opened the email (if tracking enabled)
- `email.clicked` - Recipient clicked a link (if tracking enabled)
- `message.received` - New email received in a mailbox

**Webhook Destinations:**
- HTTPS endpoints (with signature verification)
- AWS EventBridge (cross-account)
- AWS SNS topics
- AWS SQS queues

Webhooks support CloudEvents and Stripe-style payload formats with automatic retries and delivery tracking.

## Rate Limits

- **Free tier**: 100 emails/day, 1000 API requests/hour
- **Paid plans**: Higher limits available

## Error Handling

All errors return JSON with:
- `error`: Human-readable message
- `error_id`: Unique ID for support reference
- `code`: Machine-readable error code
- `hint`: Suggestion for resolution

Example:
```json
{
  "error": "Mailbox not found",
  "error_id": "err_abc123",
  "code": "MAILBOX_NOT_FOUND",
  "hint": "Check the mailbox ID and ensure you have access to it."
}
```

## Support

- **Docs**: https://agentmailbox.to/apidocs/
- **Support**: https://agentmailbox.to/support/
- **Status**: https://status.agentmail.compostable.ai

## Links

- Homepage: https://agentmailbox.to
- API Docs: https://agentmailbox.to/apidocs/
- Sign Up: https://signup.agentmail.compostable.ai
- Compostable AI: https://compostable.ai