# mails0 — Email for AI Agents

You have a hosted email address on mails0.com. You can send emails, receive emails, search your inbox, and extract verification codes. No self-hosting needed.

## Your credentials

- **Mailbox:** (set via `mails config` or passed as argument)
- **API Key:** (set via `mails config set api_key YOUR_KEY`)
- **API Base:** https://api.mails0.com

## CLI Reference

### Send email

```bash
mails send --to hello@mails0.com --subject "Hello" --body "World"
mails send --to hello@mails0.com --subject "Report" --html "<h1>Report</h1><p>See below</p>"
mails send --to hello@mails0.com --subject "Files" --body "Attached" --attach report.pdf
mails send --to hello@mails0.com --cc team@mails0.com --subject "Update" --body "FYI"
```

### Check inbox

```bash
mails inbox                                    # list recent emails
mails inbox --query "password reset"           # full-text search
mails inbox --label code                       # filter by label (code/newsletter/notification/personal)
mails inbox --direction inbound --limit 20     # inbound only, 20 results
mails inbox --threads                          # list conversation threads
mails inbox <email-id>                         # read full email with attachments
```

### Wait for verification code

```bash
mails code --to myagent@mails0.com             # wait 30s (default)
mails code --to myagent@mails0.com --timeout 60
CODE=$(mails code --to myagent@mails0.com)     # capture in variable
```

Extracts 4-8 character codes from email subject and body. Supports English, Chinese, Japanese, Korean.

### Config

```bash
mails config                         # show all settings
mails config set api_key mk_xxx      # set API key
mails config set mailbox myagent@mails0.com
mails doctor                         # verify setup works
```

## HTTP API Reference

All endpoints use `Authorization: Bearer YOUR_API_KEY` header.

Base URL: `https://api.mails0.com`

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /v1/send | Send email |
| GET | /v1/inbox | List emails (params: mailbox, limit, query, label, direction) |
| GET | /v1/inbox?query=TEXT | Full-text search |
| GET | /v1/inbox?label=LABEL | Filter by label |
| GET | /v1/email?id=ID | Get full email with attachments |
| DELETE | /v1/email?id=ID | Delete email |
| GET | /v1/code?to=ADDR&timeout=30 | Long-poll for verification code |
| GET | /v1/threads?to=ADDR | List conversation threads |
| GET | /v1/thread?id=ID&to=ADDR | Get all emails in a thread |
| POST | /v1/extract | Extract structured data (order/shipping/calendar/receipt/code) |
| GET | /v1/events | SSE stream for real-time events |
| GET | /v1/attachment?id=ID | Download attachment |
| GET | /v1/me | Account info and capabilities |

### Send email (HTTP)

```bash
curl -X POST https://api.mails0.com/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["hello@mails0.com"],"subject":"Hello","text":"World"}'
```

### Search inbox (HTTP)

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.mails0.com/v1/inbox?query=verification+code&limit=5"
```

### Wait for code (HTTP)

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.mails0.com/v1/code?to=myagent@mails0.com&timeout=30"
```

## 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")

# Wait for verification code
code = client.wait_for_code(timeout=30)
print(code)  # "847291"

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

# Search by label
emails = client.get_inbox(label="notification")
```

## Auto Labels

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

## Structured Data Extraction

Extract structured data from any email (rule-based, no LLM):

```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"}'
```

Types: `order` (order_id, total, merchant), `shipping` (tracking, carrier, eta), `calendar` (title, date, location), `receipt` (merchant, amount, date), `code` (verification code).

## Common Patterns

### Sign up for a service and extract verification code

```bash
# 1. Sign up using your agent email
# 2. Wait for the verification code
CODE=$(mails code --to myagent@mails0.com --timeout 60)
echo "Code: $CODE"
```

### Monitor inbox for new emails

```bash
mails inbox --direction inbound --limit 1
```

### Reply to an email (threading)

```bash
mails send --to hello@mails0.com \
  --subject "Re: Original Subject" \
  --body "Thanks for your email." \
  --in-reply-to "<original-message-id>"
```