mails-skills

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

---

Your agent needs an email address. To sign up for services, receive verification codes, send notifications, or monitor an inbox -- it needs email. mails-skills gives any LLM agent that ability in under 2 minutes.

What Your Agent Can Do

Capability	Example
Receive emails	"Check my inbox for new messages"
Send emails	"Send a summary report to alice@company.com"
Extract verification codes	"Sign up on example.com and enter the code"
Search inbox	"Find all emails from GitHub"
Download attachments	"Get the PDF from that invoice email"
Auto-register for services	Full flow: fill form, wait for code, verify

Quick Start

Option A: Hosted (2 commands)

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

Then install the skill:

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

Click to expand self-hosted setup

You need: a domain on Cloudflare + a free Resend account.

# 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:

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

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-8 digit verification codes
    |-- Files:   Attachments in R2, downloadable via API
    '-- 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

Manual install (without install.sh)

Claude Code:

cp skills/claude-code/email.md ~/.claude/skills/email.md
# Edit: replace YOUR_WORKER_URL, YOUR_AUTH_TOKEN, YOUR_MAILBOX

OpenClaw:

cp -r skills/openclaw ~/.openclaw/skills/email
# Add to ~/.zshrc:
export MAILS_API_URL="https://your-worker.workers.dev"
export MAILS_AUTH_TOKEN="your-token"
export MAILS_MAILBOX="agent@yourdomain.com"

Any other agent:

# Copy skills/universal/email-api.md into your agent's system prompt

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)

./install.sh --url https://your-worker.workers.dev --token YOUR_TOKEN --mailbox agent@example.com

# Or with environment variables:
MAILS_URL=https://your-worker.workers.dev MAILS_TOKEN=YOUR_TOKEN MAILS_MAILBOX=agent@example.com ./install.sh

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	Description	Users
mails	Email server (Worker) + CLI + SDK	Developers deploying email infra
mails-skills (this repo)	Skill files for AI agents	AI agents (Claude Code, OpenClaw, etc.)

Contributing

See CONTRIBUTING.md.

License

MIT