# mails0.com — Complete Reference for AI Agents

> Give your AI agent a real email address. Send, receive, search, and extract verification codes. Open source, self-hosted on Cloudflare, zero cost.

## Quick Start

1. Install: `npm install -g mails-agent`
2. Claim: visit https://mails0.com → type a name → click Claim
3. Configure: `mails config set api_key YOUR_KEY && mails config set mailbox yourname@mails0.com`
4. Test: `mails send --to hello@mails0.com --subject "Test" --body "Hello"` (you will get an auto-reply)
5. Check: `mails inbox`

For Python: `pip install mails-agent`
For MCP (Claude Desktop, Cursor, Windsurf): `npx mails-agent-mcp`
For Claude Code skills: `curl -sL https://mails0.com/agent.md > ~/.claude/skills/mails-email.md`
Browser playground: `https://mails0.com/playground/`

API base URL: https://api.mails0.com
Auth: `Authorization: Bearer YOUR_API_KEY`

## CLI Commands

```
mails send --to addr --subject "..." --body "..."      Send email
mails send --to addr --subject "..." --html "<h1>..."  Send HTML email
mails send --to addr --subject "..." --attach file.pdf Send with attachment
mails send --to a --cc b --subject "..." --body "..."  Send with CC
mails inbox                                            List recent emails
mails inbox --query "keyword"                          Full-text search
mails inbox --label code                               Filter by label
mails inbox --direction inbound --limit 20             Filter + limit
mails inbox --threads                                  List conversation threads
mails inbox <email-id>                                 Read full email
mails code --to addr                                   Wait for verification code (30s)
mails code --to addr --timeout 60                      Wait with custom timeout
mails config                                           Show all settings
mails config set api_key mk_xxx                        Set API key
mails config set mailbox myagent@mails0.com            Set default mailbox
mails doctor                                           Verify setup
```

## HTTP API Endpoints

Base: https://api.mails0.com
Auth header: `Authorization: Bearer YOUR_API_KEY`

### Send email
POST /v1/send
```json
{"to": ["hello@mails0.com"], "subject": "Hello", "text": "World"}
```
Optional fields: `html`, `cc`, `bcc`, `attachments`, `in_reply_to`

### List inbox
GET /v1/inbox?mailbox=addr&limit=20
GET /v1/inbox?query=keyword (full-text search)
GET /v1/inbox?label=code (filter: code, newsletter, notification, personal)
GET /v1/inbox?direction=inbound

### Read email
GET /v1/email?id=EMAIL_ID
Returns full email with body, headers, attachments.

### Delete email
DELETE /v1/email?id=EMAIL_ID

### Wait for verification code
GET /v1/code?to=myagent@mails0.com&timeout=30
Long-polls until a verification code arrives. Returns the code as plain text.
Extracts 4-8 character codes from subject and body. Supports EN, ZH, JA, KO.

### Threads
GET /v1/threads?to=addr — list threads with latest message preview
GET /v1/thread?id=THREAD_ID&to=addr — all emails in a thread

### Structured data extraction
POST /v1/extract
```json
{"email_id": "msg_xxx", "type": "order"}
```
Types: order (order_id, total, merchant), shipping (tracking, carrier, eta), calendar (title, date, location), receipt (merchant, amount, date), code (verification code).

### Real-time events
GET /v1/events — SSE stream, emits message.received events

### Webhooks
PATCH /v1/mailbox — set webhook_url per mailbox
Webhooks deliver message.received events with HMAC-SHA256 signature.

### Attachments
GET /v1/attachment?id=ATTACHMENT_ID

### Account info
GET /v1/me — returns mailbox, capabilities, send status

## Python SDK

```python
from mails_agent import MailsClient

client = MailsClient(
    api_url="https://api.mails0.com",
    token="YOUR_API_KEY",
    mailbox="myagent@mails0.com",
)

# Send
client.send_email(to="hello@mails0.com", subject="Hello", body="World")

# Inbox
emails = client.get_inbox(limit=10)
emails = client.get_inbox(query="receipt")
emails = client.get_inbox(label="notification")

# Read
email = client.get_email(email_id="msg_xxx")

# Verification code
code = client.wait_for_code(timeout=30)

# Async
from mails_agent import AsyncMailsClient
async with AsyncMailsClient(api_url="...", token="...", mailbox="...") as client:
    await client.send_email(to="hello@mails0.com", subject="Hi", body="Hello")
```

Install: `pip install mails-agent`

## MCP Server

For Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients.

Install: `npx mails-agent-mcp`

Config (add to MCP settings):
```json
{
  "mcpServers": {
    "mails": {
      "command": "npx",
      "args": ["mails-agent-mcp"],
      "env": {
        "MAILS_API_KEY": "YOUR_KEY",
        "MAILS_MAILBOX": "myagent@mails0.com"
      }
    }
  }
}
```

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

## Auto Labels

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

Filter: `mails inbox --label code` or `GET /v1/inbox?label=code`

## Common Patterns

### Sign up for a service and get the verification code
```bash
# Agent fills signup form with myagent@mails0.com, then:
CODE=$(mails code --to myagent@mails0.com --timeout 60)
echo "Code: $CODE"
```

### Reply to an email (threading)
```bash
mails send --to hello@mails0.com \
  --subject "Re: Original Subject" \
  --body "Thanks!" \
  --in-reply-to "<original-message-id>"
```

### Monitor for new emails
```bash
mails inbox --direction inbound --limit 1
```

### Extract order data from a confirmation email
```bash
curl -X POST https://api.mails0.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_id":"msg_xxx","type":"order"}'
```

## What is mails0?

Open-source email infrastructure for AI agents. Gives agents a complete email identity: send, receive, search, and extract verification codes. Self-hosted on Cloudflare Workers (free tier), MIT licensed.

Unlike Resend/SendGrid (send-only) or Gmail API (complex OAuth), mails0 is built for agents: one CLI install, one API key, full email capability.

## Links

- Website: https://mails0.com
- Agent reference: https://mails0.com/agent.md
- Skill file: https://mails0.com/skill.md
- Docs: https://mails0.com/docs/
- Playground: https://mails0.com/playground/
- GitHub: https://github.com/Digidai/mails
- npm: https://www.npmjs.com/package/mails-agent
- PyPI: https://pypi.org/project/mails-agent/
- MCP: https://www.npmjs.com/package/mails-agent-mcp

## FAQ

Q: What is mails0?
A: Open-source email for AI agents. Send, receive, search, extract codes. Free, self-hosted on Cloudflare.

Q: How do I give my AI agent an email address?
A: Run `npm install -g mails-agent`, visit mails0.com to claim a free @mails0.com mailbox.

Q: Can agents extract verification codes?
A: Yes. `mails code --to myagent@mails0.com` auto-extracts 4-8 char codes. Supports EN/ZH/JA/KO.

Q: Is it free?
A: Yes. MIT license. Cloudflare free tier covers everything.

Q: How is this different from AgentMail?
A: AgentMail is hosted SaaS with usage-based pricing. mails0 is open source, self-hosted, zero cost, you own your data.