MailClaw - Binary CLI

You have access to the local mailclaw binary CLI. Use it to read, search, and manage emails. Do not call the MailClaw HTTP API directly with curl unless the user explicitly asks for raw API requests.

By default, if mailclaw is missing, install it automatically and then continue the task.

Prerequisite

Before doing anything else, verify the CLI exists:

mailclaw --version

If mailclaw is missing on macOS, install it with Homebrew.
If mailclaw is missing on Linux, download the latest release binary and install it to /usr/local/bin/mailclaw.
On Windows, do not guess an install flow here. Ask the user to install the CLI manually or provide the binary path.
Once the binary is available, use it for all inbox operations.

Automatic install flow

Run the official install script, which handles both macOS (Homebrew) and Linux (GitHub Releases) automatically:

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

On macOS, the script installs via brew tap owo-network/brew && brew install owo-network/brew/mailclaw.
On Linux, the script detects the architecture, downloads the latest release binary, and installs it to /usr/local/bin/mailclaw.
After installation, the script prompts the user to configure host and API token interactively.
If writing to /usr/local/bin fails, the script will request elevated privileges automatically.
On Windows, do not run the install script. Ask the user to install the CLI manually or provide the binary path.
Reuse the installed CLI on future invocations unless the user asks for a specific version or a source build.

Configuration

Use the CLI to manage config instead of reading or writing ~/.mailclaw/config.json manually.

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

# Show current config state
mailclaw config show --json

# Verify the configured host is reachable
mailclaw health --json

If config is missing, ask the user to provide their MailClaw Host and API Token, then save them with mailclaw config set.
The CLI also supports global overrides --host <HOST> and --api-token <TOKEN>, but prefer persisted config unless the user wants a one-off override.
On Windows, ask the user for the CLI path if mailclaw is not already available on PATH.

Available Commands

List emails (metadata only)

mailclaw list [--limit N] [--offset N] [--from sender@example.com] [--to inbox@example.com] [--q keyword] [--after 2026-03-01] [--before 2026-03-11] [--json]

Returns email summaries without body content. Use this for overview and browsing.

Export emails (with full content)

mailclaw export [same filters as list] [--json]

Returns full emails including text_content and html_content. Use this when the user wants body content for multiple emails.

Get single email

mailclaw get <email_id> [--json]

Returns one full email, including body content.

Delete email

mailclaw delete <email_id> [--json]

Permanently deletes an email. Always confirm with the user before deleting.

Health check

mailclaw health [--json]

Use this to verify the configured host is correct during setup.

JSON Output

When you pass --json, the CLI prints the payload directly, not the original HTTP { success, data } envelope.

Email object (list)

{
  "id": "clx...",
  "from_address": "sender@example.com",
  "to_address": "bd@example.com",
  "subject": "Subject line",
  "received_at": 1710000000,
  "has_attachments": false,
  "attachment_count": 0
}

Email object (export / get)

Same as above, plus:

{
  "text_content": "Plain text body...",
  "html_content": "<p>HTML body...</p>"
}

Paginated response

{
  "emails": [ ... ],
  "total": 128,
  "limit": 20,
  "offset": 0
}

Usage Examples

# List all recent emails
mailclaw list --json

# Search emails containing "partnership"
mailclaw list --q partnership --json

# Filter by recipient and sender
mailclaw list --to bd@example.com --from partner@company.com --json

# Get emails from the last 7 days
mailclaw list --after 2026-03-03 --json

# Export emails with full content
mailclaw export --limit 10 --json

# Read a specific email
mailclaw get clx123abc --json

# Delete an email
mailclaw delete clx123abc --json

Limitations

MailClaw is receive-only. Replying to or sending emails is not supported. If the user asks to send or reply to an email, inform them that this feature is not yet available because Cloudflare Email Sending is still in beta (waitlist). It will be supported once the feature becomes generally available.

Guidelines

Use the CLI, not curl — All inbox operations should go through mailclaw.
Check config through the CLI — Use mailclaw config show --json and mailclaw config set ...; do not manually edit the config file unless the user explicitly asks.
Verify on first use — After saving a new config, call mailclaw health --json.
Start with list — Use mailclaw list first to get an overview, then drill into specific emails with mailclaw get <id>.
Use filters — Always apply relevant filters (from, to, q, date range) rather than fetching everything.
Prefer text_content — When displaying email content to the user, prefer text_content over html_content for readability.
Pagination — For large inboxes, paginate through results using limit and offset.
Confirm deletes — Always ask the user for confirmation before deleting emails.
Date formatting — The received_at field is a Unix timestamp in seconds. Convert it to a human-readable format when presenting to the user.

mailclaw

Safety Notice

Copy this and send it to your AI assistant to learn