mails-agent Documentation
Email infrastructure for AI agents. Give your agent a real email address in 2 minutes.
Quickstart
Install, claim a mailbox, send your first email. 2 minutes.
Messages API
Send, receive, list, search, and delete emails.
SSE Events
Real-time event stream. No public URL needed.
Code Extraction
Auto-extract verification codes in 4 languages.
Python SDK
Sync + async, 12 methods, full type hints.
MCP Server
Claude Desktop, Cursor, Windsurf integration.
API Overview
Base URL: https://mails-worker.genedai.workers.dev (hosted) or your own Worker URL (self-hosted).
Authentication via Bearer token in the Authorization header.
Endpoints
GET/v1/inbox — List emails
POST/v1/send — Send email
GET/v1/code — Wait for verification code
GET/v1/email — Get single email
DELETE/v1/email — Delete email
GET/v1/threads — List threads
GET/v1/thread — Get thread
GET/v1/search — Semantic search
GET/v1/events — SSE event stream
GET/v1/stats — Mailbox statistics
GET/v1/me — Auth info
POST/v1/extract — Structured data extraction
POST/v1/domains — Register custom domain
GET/v1/domains — List domains
GET/v1/attachment — Download attachment
GET/v1/mailbox — Get mailbox info
PATCH/v1/mailbox — Update mailbox (webhook URL, etc.)
PATCH/v1/mailbox/pause — Pause mailbox
PATCH/v1/mailbox/resume — Resume mailbox
What makes mails-agent different
| Feature | mails-agent | AgentMail | Robotomail |
|---|---|---|---|
| Pricing | Free (Cloudflare free tier) | $0-200/mo | $0-199/mo |
| Open Source | MIT full stack | SDK only | Closed |
| Self-hosted | Yes | No | No |
| Verification codes | 4 languages (EN/ZH/JA/KO) | No | No |
| Semantic search | Workers AI + Vectorize | No | No |
| MCP Server | 10 tools | Yes | No |
| Python SDK | Sync + async | Yes | No SDK |
| SSE Events | Yes | No | Yes |
| Delivery tracking | Yes | Unknown | Yes |
| Auto labels | 4 categories | No | No |
| GitHub Action | Yes | No | No |
Install
# CLI + TypeScript SDK
npm install -g mails-agent
# MCP Server (Claude Desktop, Cursor, Windsurf)
npx mails-agent-mcp
# Python SDK
pip install mails-agent
# GitHub Action
- uses: Digidai/mails-agent-action@v1
with:
api-key: ${{ secrets.MAILS_API_KEY }}