MailClaw

A Cloudflare Workers-based email inbox service. Receives all emails sent to *@yourdomain.com via catch-all Email Routing, stores them in D1, and exposes a token-protected REST API for reading and searching emails.

Built to be consumed by AI agents (Claude Code, OpenClaw, etc.) for automated email processing.

Features

Catch-all inbox — Receive emails to any address on your domain
Full-text search — Search emails by keyword in subject and body
Flexible filtering — Filter by sender, recipient, date range
Export API — Paginated export with full email content
Token authentication — All API endpoints protected with Bearer token
Edge computing — Runs on Cloudflare's global network

Tech Stack

Cloudflare Workers — Runtime
Cloudflare D1 — SQLite database
Cloudflare Email Routing — Email receiving
Hono — Web framework
postal-mime — Email parsing
Bun — Package manager

Prerequisites

Bun installed
A Cloudflare account with Workers access
A domain added to Cloudflare with Email Routing enabled

Deployment

1. Clone and install

git clone https://github.com/missuo/mailclaw
cd mailclaw
bun install

2. Authenticate with Cloudflare

bunx wrangler login

3. Create D1 database

bun run db:create

This will output a database ID. Copy it.

4. Update wrangler config

Edit wrangler.jsonc and replace REPLACE_WITH_YOUR_DATABASE_ID with the ID from step 3:

"d1_databases": [
  {
    "binding": "D1",
    "database_name": "mailclaw-d1",
    "database_id": "your-database-id-here"
  }
]

5. Initialize database

bun run db:tables
bun run db:indexes

6. Set API token

Generate a secure token and set it as a Worker secret:

# Generate a random token
openssl rand -hex 32

# Set it as a secret
bunx wrangler secret put API_TOKEN

Save this token — you'll need it to authenticate API requests.

7. Deploy

bun run deploy

Note the Worker URL from the output (e.g., https://mailclaw.<your-subdomain>.workers.dev).

8. Configure Email Routing

Go to Cloudflare Dashboard
Select your domain
Navigate to Email > Email Routing > Routing rules
Under Catch-all address, click Edit
Set action to Send to a Worker
Select the mailclaw worker
Save

All emails sent to *@yourdomain.com will now be received by MailClaw.

API Reference

All /api/emails* endpoints require the Authorization header:

Authorization: Bearer <your-api-token>

List emails

GET /api/emails

Returns email metadata (no body content). Supports pagination and filtering.

Query parameters:

| Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------------------------------------------- | | limit | number | 20 | Page size (1-100) | | offset | number | 0 | Pagination offset | | from | string | — | Filter by sender (exact match) | | to | string | — | Filter by recipient (exact match) | | q | string | — | Search keyword in subject and body | | after | string | — | Emails after date (ISO 8601 or Unix timestamp) | | before | string | — | Emails before date (ISO 8601 or Unix timestamp) |

Example:

# List recent emails
curl -H "Authorization: Bearer $TOKEN" \
  "https://mailclaw.example.com/api/emails"

# Filter by sender and date range
curl -H "Authorization: Bearer $TOKEN" \
  "https://mailclaw.example.com/api/emails?from=partner@company.com&after=2026-03-01"

# Search by keyword
curl -H "Authorization: Bearer $TOKEN" \
  "https://mailclaw.example.com/api/emails?q=partnership"

Response:

{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "clx...",
        "from_address": "partner@company.com",
        "to_address": "bd@yourdomain.com",
        "subject": "Partnership Inquiry",
        "received_at": 1710000000,
        "has_attachments": false,
        "attachment_count": 0
      }
    ],
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Export emails (with content)

GET /api/emails/export

Same parameters as list, but includes text_content and html_content in the response.

curl -H "Authorization: Bearer $TOKEN" \
  "https://mailclaw.example.com/api/emails/export?limit=10"

Get single email

GET /api/emails/:id

Returns full email including body content.

curl -H "Authorization: Bearer $TOKEN" \
  "https://mailclaw.example.com/api/emails/clx123abc"

Delete email

DELETE /api/emails/:id

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://mailclaw.example.com/api/emails/clx123abc"

Health check

GET /api/health

No authentication required.

curl "https://mailclaw.example.com/api/health"

Rust CLI

MailClaw also ships with a Rust binary CLI named mailclaw. It wraps the same API endpoints and stores local credentials in ~/.mailclaw/config.json.

Build or install

# Install into ~/.cargo/bin/mailclaw
cargo install --path .

# Or build a local release binary
cargo build --release
./target/release/mailclaw --help

Configure

mailclaw config set \
  --host "https://mailclaw.example.com" \
  --api-token "your-api-token-here"

mailclaw health

Common commands

# List recent email metadata
mailclaw list --limit 10

# Search emails and return machine-readable JSON
mailclaw list --q partnership --json

# Export full content
mailclaw export --from partner@company.com --limit 5 --json

# Read one email
mailclaw get clx123abc

# Delete one email
mailclaw delete clx123abc

Quick install (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/missuo/mailclaw/main/install.sh | bash

On macOS the script installs via Homebrew; on Linux it downloads the latest release binary for your architecture.

Prebuilt binaries

GitHub Releases publish prebuilt CLI binaries for:

x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu
x86_64-apple-darwin
aarch64-apple-darwin
x86_64-pc-windows-msvc

If you prefer to install manually, download the binary for your platform from the latest release, rename it if needed, and put it on your PATH. The uploaded asset names follow this pattern:

mailclaw-v1.0.0-<target>
mailclaw-v1.0.0-<target>.exe

Release automation

Pushing a tag like v0.1.0 triggers .github/workflows/release-cli.yml, which creates a GitHub Release and uploads the compiled CLI binaries directly.

git tag v0.1.0
git push origin v0.1.0

AI Agent Skills

MailClaw ships with a built-in skill that lets AI agents (Claude Code, OpenClaw, etc.) read and manage your inbox.

Add to Claude Code

npx skills add missuo/mailclaw

The skill now shells out to the local mailclaw CLI instead of calling curl directly. If the CLI is missing, the skill should install the latest release binary automatically by default on macOS, Linux, and Windows.

On first use, the skill will ask you for your MailClaw Host and API Token, then save them through mailclaw config set to ~/.mailclaw/config.json for future sessions.

Once installed, you can use natural language like:

"Check my recent emails"
"Search emails from partner@company.com"
"Read the latest email about partnership"
"Show me all emails sent to tcook@apple.com this week"

The skill will automatically use the local mailclaw CLI to fetch and display results.

Add to other AI agents

The skill definition is located at skills/mailclaw/SKILL.md. You can copy or adapt it for any AI agent framework that supports markdown-based skill definitions, or invoke the mailclaw CLI directly.

Limitations

MailClaw currently supports receiving and reading emails only. Replying to and sending emails are not yet supported because Cloudflare Email Sending is still in beta with a waitlist. We will add send/reply support once the feature becomes generally available.

Local Development

Create a .dev.vars file for local secrets:

API_TOKEN=dev-token-here

Start the dev server:

bun run dev

License

MIT

Mailclaw

Install / Use

README