# Mails for Agent

Adopt this skill: https://proskills.md/skills/other/digidai-mails-skills-skills-openclaw

Page: https://proskills.md/skills/other/digidai-mails-skills-skills-openclaw
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/openclaw/SKILL.md
size: 5553
upstream: https://github.com/digidai/mails-skills/blob/main/skills/openclaw/SKILL.md

```text
---
name: Mails for Agent
description: "Complete service registrations autonomously by receiving verification codes. Also: send and receive emails, monitor inbox, search by keyword, download attachments, view threads, filter by label, extract structured data, manage mailbox and webhooks."
version: 1.8.0
metadata:
  openclaw:
    requires:
      env:
        - MAILS_API_URL
        - MAILS_AUTH_TOKEN
        - MAILS_MAILBOX
      bins: []
      primaryEnv: MAILS_AUTH_TOKEN
---

# Email Skill — Agent Auth-Completion

You have the email address `$MAILS_MAILBOX`. Your primary superpower: **complete service registrations autonomously** by receiving verification codes via `GET /api/code?timeout=60`.

Make HTTP requests to `$MAILS_API_URL` with header `Authorization: Bearer $MAILS_AUTH_TOKEN`.

**Sign up for a service:** Fill form with `$MAILS_MAILBOX` → GET /api/code?timeout=60 → enter the code. Done.

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/inbox | List/search emails. Params: `query`, `limit`, `offset`, `direction`, `label`, `mode` (keyword/semantic/hybrid) |
| GET | /api/email?id=ID | Full email with body, attachments, labels |
| GET | /api/code?timeout=60 | Wait for verification code (long-poll). Params: `timeout`, `since` |
| POST | /api/send | Send email. Body: `{ from, to[], cc[], bcc[], subject, text, html, reply_to, in_reply_to, headers, attachments }` |
| DELETE | /api/email?id=ID | Delete email and attachments |
| GET | /api/attachment?id=ID | Download attachment |
| GET | /api/threads | List conversation threads. Params: `limit`, `offset` |
| GET | /api/thread?id=ID | Get all emails in a thread |
| POST | /api/extract | Extract structured data. Body: `{ email_id, type }` type: order/shipping/calendar/receipt/code |
| GET | /api/stats | Mailbox statistics (total, inbound, outbound, this month) |
| GET | /api/events | SSE real-time event stream. Params: `types`, `since` |
| GET | /api/mailbox | Mailbox info (status, webhook_url) |
| PATCH | /api/mailbox | Update mailbox settings. Body: `{ webhook_url }` |
| PATCH | /api/mailbox/pause | Pause mailbox (blocks all operations) |
| PATCH | /api/mailbox/resume | Resume paused mailbox |
| GET | /api/mailbox/routes | List per-label webhook routes |
| PUT | /api/mailbox/routes | Upsert webhook route. Body: `{ label, webhook_url }` |
| DELETE | /api/mailbox/routes?label=X | Delete webhook route for label |
| GET | /api/me | Mailbox info and capabilities |
| GET | /health | Health check (no auth) |

## Request Format

All requests (except /health) require `Authorization: Bearer $MAILS_AUTH_TOKEN` header.

POST/PUT/PATCH requests require `Content-Type: application/json` header.

The `to` param is optional — the API auto-scopes to the token's mailbox.

## Response Shapes

**Inbox**: `{ "emails": [{ "id", "from_address", "from_name", "subject", "code", "direction", "status", "received_at", "has_attachments", "attachment_count" }], "search_mode": "keyword" }`

**Email detail**: Full email object with `body_text`, `body_html`, `headers`, `metadata`, `labels`, `thread_id`, `in_reply_to`, `references`, `attachments[]`

**Code**: `{ "id": "...", "code": "483920", "from": "...", "subject": "...", "received_at": "..." }` or `{ "code": null }`

**Send**: `{ "id": "...", "provider_id": "...", "thread_id": "..." }`

**Threads**: `{ "threads": [{ "thread_id", "latest_email_id", "subject", "from_address", "from_name", "received_at", "message_count", "has_attachments" }] }`

**Stats**: `{ "mailbox", "total_emails", "inbound", "outbound", "emails_this_month", "ingest": { "pending", "parsed", "failed" } }`

**Extract**: `{ "email_id": "...", "extraction": { "type": "order", "order_id": "...", ... } }`

**Events (SSE)**: `event: message.received\ndata: { "email_id", "mailbox", "from", "subject", ... }`

## Send Fields

| Field | Required | Description |
|-------|----------|-------------|
| from | Yes | Must be `$MAILS_MAILBOX` (enforced server-side) |
| to | Yes | Array of recipients (max 50) |
| subject | Yes | Max 998 characters |
| text | text or html | Plain text body |
| html | text or html | HTML body |
| cc | No | Array of CC recipients |
| bcc | No | Array of BCC recipients |
| reply_to | No | Reply-to address |
| in_reply_to | No | Message-ID of parent email (enables threading) |
| headers | No | Custom headers object |
| attachments | No | `[{ filename, content (base64), content_type?, content_id? }]` |

## Labels

Emails are auto-labeled on receive: `newsletter`, `notification`, `code`, `personal`. Filter with `?label=notification`.

## Common Flows

**Sign up for a service:** Fill form with `$MAILS_MAILBOX` → GET /api/code?timeout=60 → enter the code

**Process inbox:** GET /api/inbox → GET /api/email?id=ID → DELETE /api/email?id=ID

**Reply to an email:** GET /api/email?id=ID → POST /api/send with `in_reply_to` set to the email's `message_id`

**View threads:** GET /api/threads → GET /api/thread?id=THREAD_ID

**Monitor in real-time:** GET /api/events (SSE stream, reconnects automatically)

**Extract data:** POST /api/extract with `{"email_id":"ID","type":"order"}`

**Set up webhook routing:** PUT /api/mailbox/routes with `{"label":"code","webhook_url":"https://..."}`

## Constraints

- `from` must match `$MAILS_MAILBOX`
- Verification codes: 4-12 alphanumeric (EN/ZH/JA/KO)
- Code wait timeout max 55 seconds
- Send rate limit: 100 emails/day per mailbox
- Search uses FTS5 full-text search (keyword mode) or Vectorize (semantic mode)
```

## File: README.md
upstream: https://github.com/digidai/mails-skills/blob/main/README.md

````text
<p align="center">
  <h1 align="center">mails-skills</h1>
  <p align="center">
    Your AI agent can now sign up for any service. Verification codes handled automatically.
  </p>
  <p align="center">
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
    <a href="#supported-platforms"><img src="https://img.shields.io/badge/platforms-Claude_Code_%7C_OpenClaw_%7C_Cursor_%7C_Any_Agent-brightgreen.svg" alt="Platforms"></a>
    <a href="https://www.npmjs.com/package/mails-agent"><img src="https://img.shields.io/npm/v/mails-agent.svg?label=mails-agent%20CLI" alt="npm version"></a>
  </p>
</p>

---

**Your agent hits "enter verification code" and stops.** Not anymore. `mails-skills` gives any AI agent the ability to receive verification codes and complete service registrations autonomously. One API call: `GET /api/code?timeout=60`.

## What Your Agent Can Do

| Capability | Example |
|---|---|
| **Auto-register for services** | **Full flow: fill form, wait for code, verify. Zero human intervention.** |
| **Extract verification codes** | **"Sign up on example.com and enter the code"** |
| Receive emails | "Check my inbox for new messages" |
| Send emails | "Send a summary report to alice@company.com" |
| Search inbox | "Find all emails from GitHub" |
| Download attachments | "Get the PDF from that invoice email" |
| Conversation threads | "Show me the full thread with Alice" |
| Filter by label | "Show me all newsletters" (newsletter, notification, code, personal) |
| Extract structured data | "Extract the order details from that confirmation email" (order, shipping, calendar, receipt) |

## Quick Start

### Option A: Hosted (2 commands)

```bash
npm install -g mails-agent    # Install the CLI
mails claim myagent           # Claim myagent@mails0.com (free)
```

Then install the skill:

```bash
git clone https://github.com/Digidai/mails-skills && cd mails-skills && ./install.sh
```

The installer auto-detects your config from `mails claim` -- no manual input needed.

### Option B: Self-hosted

<details>
<summary>Click to expand self-hosted setup</summary>

You need: a domain on Cloudflare + a free [Resend](https://resend.com) account.

```bash
# 1. Deploy the Worker
git clone https://github.com/Digidai/mails && cd mails/worker
bun install

# 2. Create D1 database
wrangler d1 create mails
# Copy the database_id into wrangler.toml

# 3. Initialize schema
wrangler d1 execute mails --file=schema.sql

# 4. Set secrets
wrangler secret put RESEND_API_KEY
wrangler secret put WEBHOOK_SECRET     # Optional: for webhook signing

# 5. Deploy
wrangler deploy
# Note the Worker URL: https://mails-worker.<subdomain>.workers.dev

# 6. Enable Email Routing in Cloudflare Dashboard
#    Domain > Email > Email Routing > Enable
#    Catch-all > Send to Worker > your-worker

# 7. Add Resend DNS records (SPF + DKIM) in Cloudflare DNS
#    See: https://resend.com/docs/dashboard/domains/introduction

# 8. Create an auth token
wrangler d1 execute mails --command \
  "INSERT INTO auth_tokens (token, mailbox) VALUES ('$(openssl rand -hex 24)', 'agent@yourdomain.com')"
```

Then install the skill:

```bash
git clone https://github.com/Digidai/mails-skills && cd mails-skills && ./install.sh
```

</details>

## How It Works

```
Your Agent (Claude Code / OpenClaw / Cursor / any LLM)
    |
    |  "Check inbox" / "Send email" / "Get verification code"
    v
Skill file (installed locally, teaches the agent the API)
    |
    |  HTTP API calls
    v
mails Worker (Cloudflare Workers + D1 + R2)
    |-- Receive: Cloudflare Email Routing -> Worker -> D1
    |-- Send:    Worker -> Resend API -> SMTP
    |-- Search:  FTS5 full-text search
    |-- Codes:   Auto-extract 4-12 char verification codes
    |-- Files:   Attachments in R2, downloadable via API
    |-- Threads: Conversation threading by subject/references
    |-- Labels:  Auto-categorize (newsletter, notification, code, personal)
    |-- Extract: Structured data extraction (order, shipping, calendar, receipt)
    '-- Hooks:   Webhook POST on every received email
```

## Supported Platforms

| Platform | How it works | Install |
|---|---|---|
| **Claude Code** | Skill file in `~/.claude/skills/` | `./install.sh` (auto-detected) |
| **OpenClaw** | SKILL.md with env vars | `./install.sh` (auto-detected) |
| **Cursor** | Rules file | Add `skills/universal/email-api.md` to `.cursorrules` |
| **Windsurf** | Rules file | Add `skills/universal/email-api.md` to `.windsurfrules` |
| **Any agent** | HTTP API reference | Include `skills/universal/email-api.md` in system prompt |

<details>
<summary>Manual install (without install.sh)</summary>

**Claude Code:**
```bash
cp skills/claude-code/email.md ~/.claude/skills/email.md
# Edit: replace YOUR_WORKER_URL, YOUR_AUTH_TOKEN, YOUR_MAILBOX
```

**OpenClaw:**
```bash
cp -r skills/openclaw ~/.openclaw/skills/email
# Add to ~/.zshrc:
export MAILS_API_URL="https://api.mails0.com"   # self-hosted: your https://<worker>.workers.dev
export MAILS_AUTH_TOKEN="your-token"
export MAILS_MAILBOX="agent@mails0.com"
```

**Any other agent:**
```bash
# Copy skills/universal/email-api.md into your agent's system prompt
```
</details>

## Example: Agent Signs Up for a Service

```
You:   "Sign up for an account on example.com using our email"

Agent: 1. Opens example.com/register
       2. Fills in the form with agent@mails0.com
       3. Submits the form
       4. Calls GET /api/code?timeout=60
       5. Receives { "code": "483920" }
       6. Enters 483920 on the verification page
       7. "Done! Account created successfully."
```

## Non-Interactive Install (CI / Automation)

```bash
# Hosted (default)
./install.sh --url https://api.mails0.com --token YOUR_TOKEN --mailbox agent@mails0.com

# Or with environment variables:
MAILS_URL=https://api.mails0.com MAILS_TOKEN=YOUR_TOKEN MAILS_MAILBOX=agent@mails0.com ./install.sh

# Self-hosted: replace the URL with your own Worker, e.g. https://mails-worker.<subdomain>.workers.dev
```

## Captcha Limitation

Most modern SaaS services (Render, Figma, etc.) use captcha challenges that block fully autonomous agent registration. mails-skills handles the email/OTP side, captcha is a browser-layer problem.

**Recommended solutions:**
- [Steel](https://steel.dev) -- open-source browser API with built-in captcha solving
- [Browserbase](https://www.browserbase.com) -- cloud browsers with captcha solving + Agent Identity
- [CapSolver](https://www.capsolver.com) -- captcha solving API ($0.80/1K solves), browser extension available
- [Web Bot Auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) -- emerging IETF protocol for verified bot identity (Cloudflare, AWS, Akamai support)

## Troubleshooting

| Problem | Solution |
|---|---|
| `python3 not found` | `brew install python3` (macOS) or `apt install python3` (Linux) |
| `invalid auth token` | Re-run `mails claim` or check `~/.mails/config.json` |
| Cannot reach Worker URL | Verify the URL and that the Worker is deployed |
| Agent doesn't know about email | Check skill file exists: `ls ~/.claude/skills/email.md` |
| Verification code not found | The email may lack a parseable code. Read the full email with `GET /api/email?id=...` |
| `mails claim` hangs | Check your internet connection; the hosted service may be temporarily unavailable |

## Project Structure

```
skills/
  claude-code/email.md     # Claude Code skill
  openclaw/SKILL.md        # OpenClaw AgentSkills format
  universal/email-api.md   # Universal API reference (Python, JS, cURL)
install.sh                 # Interactive + non-interactive installer
```

## Ecosystem

| Project | Install | Description |
|---|---|---|
| **[mails](https://github.com/Digidai/mails)** | `npm i -g mails-agent` | CLI + SDK + Worker |
| **[mails-mcp](https://github.com/Digidai/mails-mcp)** | `npx mails-agent-mcp` | MCP Server (10 tools) |
| **[mails-python](https://github.com/Digidai/mails-python)** | `pip install
````
