mails-agent

Email infrastructure for AI agents. Send, receive, search, and extract verification codes.

日本語 | 中文

Agent Integration: Use mails-skills to give your Claude Code, OpenClaw, or any AI agent email capabilities with one command.

Why mails?

Unlike raw email APIs that only send, mails gives your agent a complete email identity — send, receive, search, and extract verification codes in one package. Deploy on your own domain with Cloudflare (free tier). Full control, no third-party dependency.

Features

• Send emails — via Resend with CC/BCC, In-Reply-To threading, and attachment support
• Receive emails — via Cloudflare Email Routing → Worker → D1, with raw-first R2 persistence (zero email loss)
• Search inbox — FTS5 full-text search across subject, body, sender, code
• Semantic search — AI-powered vector search via Workers AI + Cloudflare Vectorize (keyword, semantic, hybrid modes)
• Dashboard console — visual email management UI at mails0.com/console
• Verification code extraction — auto-extracts 4-8 char codes (EN/ZH/JA/KO)
• Email threading — auto-assign thread_id via In-Reply-To / References headers
• Auto labels — rule-based classification: newsletter, notification, code, personal
• Structured data extraction — extract orders, shipping, calendar, receipts from emails (rule-based, no LLM)
• Attachments — send via CLI (--attach) or SDK; receive with R2 storage for large files
• Webhook notifications — POST to your URL on email receive, with HMAC-SHA256 signature verification
• SSE real-time events — subscribe to message.received events via /api/events
• Mailbox isolation — per-token mailbox binding via auth_tokens D1 table with scoped keys
• Mailbox pause/resume — temporarily stop processing for a mailbox
• Suppression list — auto-suppress bounced/complained recipients, protects domain reputation
• Rate limits — per-mailbox daily send limits (configurable via DAILY_SEND_LIMIT)
• Custom domains — manage and verify custom sending domains via API
• Inbound idempotency — deduplication via message_id, safe against replay/redelivery
• Smart email routing — per-label webhook URLs, route different email types (code/newsletter/notification/personal) to different endpoints
• Mailbox CRUD — update webhook URL via PATCH /api/mailbox, cascade delete via DELETE /api/mailbox
• One-click deploy — mails deploy automates the entire self-hosting setup (D1, secrets, Worker) via wrangler
• Delete API — remove processed emails with cascade cleanup (attachments + R2)
• Storage providers — local SQLite (dev) or remote Worker API (production)
• Zero runtime dependencies — all providers use raw fetch()
• Self-hosted — deploy your own Worker on Cloudflare (free tier), full control over your data

Install

npm install -g mails-agent
# or
bun install -g mails-agent
# or use directly
npx mails-agent

Quick Start

# 1. Deploy your Worker (see Self-Hosted Deployment guide below)
cd worker && wrangler deploy

# 2. Configure the CLI
mails config set worker_url https://your-worker.example.com
mails config set worker_token YOUR_TOKEN
mails config set mailbox [email protected]
mails config set default_from [email protected]

# 3. Use it
mails send --to [email protected] --subject "Hello" --body "World"
mails inbox                          # List received emails
mails inbox --query "password"       # Search emails
mails code --to [email protected] # Wait for verification code

How it works

                          SENDING                                    RECEIVING

  Agent                                              External
    |                                                  |
    |  mails send --to [email protected]                |  email to [email protected]
    |                                                  |
    v                                                  v
+--------+                                   +-------------------+
|  CLI   |------ /api/send ----------------->| Cloudflare Email  |
|  /SDK  |<----- /api/inbox -----------------|     Routing       |
+--------+                                   +-------------------+
    |                                                  |
    v                                                  v
+--------------------------------------------------+
|              Your Cloudflare Worker               |
|  /api/send → Resend API → SMTP delivery          |
|  /api/inbox, /api/code → D1 query (FTS5 search)  |
|  email() handler → parse MIME → store in D1       |
+--------------------------------------------------+
    |               |
    v               v
+--------+    +------------+
|   D1   |    |     R2     |
| emails |    | attachments|
+--------+    +------------+
    |
    |  query via CLI/SDK
    v
  Agent
    mails inbox
    mails inbox --query "code"
    mails code --to [email protected]

CLI Reference

send

mails send --to <email> --subject <subject> --body <text>
mails send --to <email> --subject <subject> --html "<h1>Hello</h1>"
mails send --from "Name <email>" --to <email> --subject <subject> --body <text>
mails send --to <email> --subject "Report" --body "See attached" --attach report.pdf

inbox

mails inbox                                  # List recent emails
mails inbox --mailbox [email protected]         # Specific mailbox
mails inbox --query "password reset"         # Search emails
mails inbox --query "invoice" --direction inbound --limit 10
mails inbox <id>                             # View email details + attachments

code

mails code --to [email protected]              # Wait for code (default 30s)
mails code --to [email protected] --timeout 60 # Custom timeout

The code is printed to stdout for easy piping: CODE=$(mails code --to [email protected])

config

mails config                    # Show all config
mails config set <key> <value>  # Set a value
mails config get <key>          # Get a value

deploy

One-click self-hosting setup. Automates D1 creation, schema migration, secret setup, and Worker deployment.

cd worker
mails deploy                    # Automated setup via wrangler

Prerequisites: wrangler login and a Cloudflare account. The command generates a random AUTH_TOKEN and prompts for RESEND_API_KEY.

SDK Usage

import { send, getInbox, searchInbox, getEmail, deleteEmail, waitForCode } from 'mails-agent'

// Send
const result = await send({
  to: '[email protected]',
  subject: 'Hello',
  text: 'World',
})

// Send with attachment
await send({
  to: '[email protected]',
  subject: 'Report',
  text: 'See attached',
  attachments: [{ path: './report.pdf' }],
})

// List inbox
const emails = await getInbox('[email protected]', { limit: 10 })

// Search inbox
const results = await searchInbox('[email protected]', {
  query: 'password reset',
  direction: 'inbound',
})

// Get email details (with attachments)
const email = await getEmail('email-id')

// Delete email (cascade: attachments + R2)
await deleteEmail('email-id')

// Wait for verification code
const code = await waitForCode('[email protected]', { timeout: 30 })
if (code) console.log(code.code) // "123456"

Storage Providers

The CLI auto-detects the storage provider:

• worker_url in config → remote (queries Worker API)
• Otherwise → local SQLite (~/.mails/mails.db)

Run the entire email system on your own domain using Cloudflare + Resend. Full control, no third-party dependency.

Prerequisites

Step 1: Add domain to Cloudflare

If your domain's DNS is not already on Cloudflare, add it at dash.cloudflare.com. Update your registrar's nameservers to the ones Cloudflare provides.

Step 2: Set up Resend for sending

1. Create a Resend account
2. Go to Domains → Add Domain → enter your domain (e.g. example.com)
3. Resend will give you DNS records to add. Go to Cloudflare DNS and add:
   • SPF — TXT record on @: v=spf1 include:amazonses.com ~all (Resend uses SES)
   • DKIM — CNAME records as provided by Resend (usually 3 records)
   • DMARC — TXT record on _dmarc: v=DMARC1; p=none; (start with none, tighten later)
4. Wait for Resend to verify your domain (usually minutes, can take up to 48h)
5. Copy your Resend API key (re_...) from the Resend dashboard

Step 3: Deploy the Worker

cd worker
bun install

# Create D1 database
wrangler d1 create mails
# → Copy the database_id from the output

# Edit wrangler.toml — paste your database_id
# Replace REPLACE_WITH_YOUR_DATABASE_ID with the actual ID

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

# Set secrets
wrangler secret put AUTH_TOKEN         # Choose a strong random token
wrangler secret put RESEND_API_KEY     # Paste your re_... key from Resend

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

Step 4: Set up Cloudflare Email Routing

1. Go to Cloudflare Dashboard → your domain → Email → Email Routing
2. Click Enable Email Routing (Cloudflare will add MX records automatically)
3. Go to Routing rules → Catch-all address → set action to Send to a Worker → select your deployed Worker
4. Now all emails to *@example.com will be routed to your Worker

Step 5: (Optional) Create R2 bucket for large attachments

wrangler r2 create mails-attachments

The R2 binding is already configured in wrangler.toml. Redeploy after creating the bucket:

wrangler deploy

Step 6: Configure the CLI

mails config set worker_url https://mails-worker.<your-subdomain>.workers.dev
mails config set worker_token YOUR_AUTH_TOKEN       # Same token from Step 3
mails config set mailbox [email protected]          # Your email address
mails config set default_from [email protected]     # Default sender

Step 7: Verify

# Check Worker is reachable
curl https://mails-worker.<your-subdomain>.workers.dev/health

# Check inbox (should be empty)
mails inbox

# Send a test email
mails send --to [email protected] --subject "Test" --body "Hello from self-hosted mails"

# Send an email TO your mailbox from any email client, then:
mails inbox

Architecture after setup

Your Agent                              External sender
    |                                        |
    |  mails send / mails inbox              |  email to [email protected]
    v                                        v
+--------+                         +-------------------+
|  CLI   |------ /api/send ------->|  Cloudflare Email |
|  /SDK  |<----- /api/inbox -------|     Routing       |
+--------+                         +-------------------+
    |                                        |
    v                                        v
+--------------------------------------------------+
|              Your Cloudflare Worker               |
|  /api/send → Resend API → SMTP delivery          |
|  /api/inbox, /api/code → D1 query (FTS5 search)  |
|  email() handler → parse MIME → store in D1       |
+--------------------------------------------------+
    |               |
    v               v
+--------+    +------------+
|   D1   |    |     R2     |
| emails |    | attachments|
+--------+    +------------+

Worker Secrets Reference

Worker API Endpoints

Send Priority

When the CLI/SDK sends an email, it checks config in this order:

1. worker_url → sends via your Worker's /api/send (recommended)
2. resend_api_key → sends directly to Resend API

Once worker_url is set, you don't need resend_api_key on the client — the Worker holds the Resend key as a secret.

bun test              # Unit + mock E2E tests
bun test:coverage     # With coverage report
bun test:live         # Live E2E with real Resend + Cloudflare (requires .env)

360 tests across 44 test files.

Ecosystem

┌─────────────────────────────────────────────────────────────┐
│                        mails ecosystem                       │
│                                                              │
│  ┌──────────────┐    ┌──────────────────┐    ┌───────────┐  │
│  │  mails CLI   │    │  mails Worker    │    │   mails   │  │
│  │  & SDK       │───▶│  (Cloudflare)    │◀───│  -skills  │  │
│  │              │    │                  │    │           │  │
│  │ npm i mails- │    │  Receive + Send  │    │  Agent    │  │
│  │    agent     │    │                  │    │           │  │
│  │              │    │  + Search + Code │    │  Skills   │  │
│  └──────────────┘    └──────────────────┘    └───────────┘  │
│    Human / Script        Infrastructure        AI Agents    │
└─────────────────────────────────────────────────────────────┘

Quick agent setup:

# MCP Server (Claude Desktop / Cursor)
npm install -g mails-agent-mcp

# Python SDK
pip install mails-agent

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

Contributing

See CONTRIBUTING.md for development setup, project structure, and PR guidelines.

Acknowledgments

This project is based on mails by turing, originally created as email infrastructure for AI agents. We forked and extended it with mailbox isolation, webhook notifications, delete API, R2 attachment storage, Worker file refactoring, and comprehensive test coverage (360 tests). Thank you to the original author for the excellent foundation.

License

MIT — see LICENSE for details. Original copyright retained per MIT terms.