# mails0.com — Email Infrastructure for AI Agents

> Give your AI agent a real email address. Send, receive, search, and extract verification codes.

## What is mails-agent?

mails-agent is open-source email infrastructure purpose-built for AI agents. Unlike raw email APIs (Resend, SendGrid, Gmail API) that only handle one part of email, mails-agent gives an agent a complete email identity — send, receive, search, and extract verification codes — in one package.

## Key Features

- Send emails with attachments via Resend API
- Receive emails via Cloudflare Email Routing → Worker → D1
- Full-text search (FTS5) across subject, body, sender
- Auto-extract 4-8 char verification codes (English, Chinese, Japanese, Korean)
- Webhook notifications with HMAC-SHA256 signing
- Per-mailbox token isolation (auth_tokens table)
- R2 attachment storage for large files (>100KB auto-upload)
- Delete API with cascade cleanup (attachments + R2)
- CLI + SDK + Agent Skills (Claude Code, OpenClaw, Cursor)
- MCP Server for Claude Desktop, Cursor, Windsurf (npx mails-agent-mcp)
- Python SDK (pip install mails-agent)
- Email threading (In-Reply-To / References → thread_id)
- Auto labels: newsletter, notification, code, personal
- Structured data extraction: orders, shipping, calendar, receipts (rule-based, no LLM)
- Semantic search via Workers AI embeddings + Cloudflare Vectorize (keyword, semantic, hybrid modes)
- Dashboard console for visual email management (mails0.com/console)

## Quick Start

1. Install: `npm install -g mails-agent` (or `pip install mails-agent` for Python)
2. Claim a mailbox: visit https://mails0.com and click Claim
3. Send: `mails send --to user@example.com --subject "Hello" --body "World"`
4. Receive: `mails inbox`
5. Search: `mails inbox --query "verification code"`
6. Wait for code: `mails code --to myagent@mails0.com`

## Agent Integration

- OpenClaw: `clawhub install mails-for-agent`
- npx: `npx mails-skills`
- Manual: `curl -sL mails0.com/skill.md > ~/.claude/skills/email.md`

## MCP Server

Connect any MCP-compatible client (Claude Desktop, Cursor, Windsurf) to email:

```
npx mails-agent-mcp
```

Provides tools: send_email, get_inbox, search_inbox, wait_for_code, get_email, delete_email, get_attachment, get_threads, get_thread, extract_data.

## Email Threads

Emails are automatically grouped into threads using In-Reply-To and References headers:

- `GET /api/threads` — list threads with latest message preview and count
- `GET /api/thread?id=<thread_id>` — all emails in a thread (chronological)
- CLI: `mails inbox --threads`

## Auto Labels

Emails are auto-labeled on receive:
- `newsletter` — List-Unsubscribe or List-Id header present
- `notification` — from noreply@, alerts@, notifications@, mailer-daemon@, bounce@
- `code` — contains a verification code
- `personal` — none of the above

Filter: `GET /api/inbox?label=notification` or `mails inbox --label notification`

## Structured Data Extraction

Extract structured data from emails on demand (rule-based, no LLM):

- `POST /api/extract` with `{ "email_id": "...", "type": "order|shipping|calendar|receipt|code" }`
- **order**: order_id, total, currency, merchant
- **shipping**: tracking_number, carrier, eta, status (UPS/FedEx/USPS/DHL)
- **calendar**: title, date, time, location, attendees (ICS parsing)
- **receipt**: merchant, amount, currency, date, payment_method
- **code**: verification code

## Python SDK

```
pip install mails-agent
```

```python
from mails_agent import MailsClient

client = MailsClient(
    api_url="https://mails-worker.genedai.workers.dev",
    token="your-api-token",
    mailbox="agent@mails0.com",
    hosted=True,
)
client.send(to="user@example.com", subject="Hello", text="World")
emails = client.get_inbox(limit=10)
code = client.wait_for_code(timeout=60)
```

## Links

- Website: https://mails0.com
- npm (CLI): https://www.npmjs.com/package/mails-agent
- npm (MCP): https://www.npmjs.com/package/mails-agent-mcp
- PyPI: https://pypi.org/project/mails-agent/
- GitHub (main): https://github.com/Digidai/mails
- GitHub (MCP): https://github.com/Digidai/mails-mcp
- GitHub (Python): https://github.com/Digidai/mails-python
- GitHub (Skills): https://github.com/Digidai/mails-skills
- ClawHub: https://clawhub.ai/digidai/mails-for-agent
- Skill file: https://mails0.com/skill.md

## Technical Details

- Runtime: Cloudflare Workers (free tier)
- Database: Cloudflare D1 (SQLite)
- Storage: Cloudflare R2 (attachments)
- SMTP: Resend API
- Search: FTS5 full-text search
- Auth: per-mailbox token isolation
- License: MIT

## Frequently Asked Questions

Q: What is mails-agent?
A: Open-source email infrastructure for AI agents. Send, receive, search emails, and extract verification codes programmatically. Deploy on Cloudflare Workers (free tier).

Q: How do I give my AI agent an email address?
A: Install with `npm install -g mails-agent` (or `pip install mails-agent` for Python), then visit mails0.com to claim a free @mails0.com mailbox. For Claude Code, run `npx mails-skills`. For MCP clients (Claude Desktop, Cursor, Windsurf), run `npx mails-agent-mcp`.

Q: Can AI agents extract verification codes from emails?
A: Yes. mails-agent auto-extracts 4-8 character codes from emails. Supports English, Chinese, Japanese, Korean. Use `mails code --to agent@mails0.com`.

Q: Is it free?
A: Yes. MIT license, fully open source. Cloudflare free tier covers Workers, D1, R2, and Email Routing.

Q: How is this different from Resend or SendGrid?
A: Resend/SendGrid are send-only APIs. mails-agent gives agents a complete email identity — send AND receive, plus search, verification code extraction, webhook notifications, and mailbox isolation.

## Comparisons

| Feature | mails-agent | Raw Resend/SendGrid | Gmail API |
|---------|-------------|---------------------|-----------|
| Send emails | Yes | Yes | Yes |
| Receive emails | Yes | No | Yes (complex OAuth) |
| Search inbox | Yes (FTS5) | No | Yes |
| Extract codes | Yes (auto) | No | No |
| Agent-friendly | Yes (CLI/SDK) | Partial | No |
| Self-hosted | Yes (free) | No | No |
| Setup time | 2 minutes | 5 minutes | 30+ minutes |