# Agent Mailbox

> 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/

### 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/

## MCP Integration

Agent Mailbox provides MCP (Model Context Protocol) servers for AI assistants including Claude Desktop, Claude Code, Cursor, Windsurf, Continue.dev, Cline, and other MCP-compatible clients.

The REST API also works with ChatGPT, Gemini, GitHub Copilot, Replit Agent, LangChain agents, AutoGPT, CrewAI, and any AI system that can make HTTP requests.

### Available MCP Tools
- `send_email` - Send emails with attachments
- `list_emails` - List inbox messages
- `read_email` - Read email content and attachments
- `track_email` - Check delivery status
- `create_mailbox` - Create new mailboxes
- `list_mailboxes` - List tenant mailboxes

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

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

### OAuth2 (MCP)
For MCP servers. Supports:
- Client Credentials flow (M2M)
- Authorization Code flow (Browser)

## 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.

### Webhooks
Real-time HTTP callbacks for email events. Configure webhooks at the tenant or mailbox level to receive notifications when:
- **Delivery**: Email successfully delivered to recipient
- **Bounce**: Email bounced (hard or soft bounce)
- **Complaint**: Recipient marked email as spam
- **Inbound**: New email received in a mailbox

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

## Support

- **Docs**: https://agentmailbox.to/apidocs/
- **Support**: https://agentmailbox.to/support/

## Links

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