mails0email API for agents

Open-source email infrastructure for agents that need inboxes, verification-code extraction, search, replies, MCP tools, and self-hosted Cloudflare control.

Permanent named mailbox · human approval

@mails0.com

Mailbox

API Key

Save your API key now — it won't be shown again.

Paste this once in Claude Code — installs, configures, and teaches your agent

# Install mails0 email for your agent ([email protected]) npm install -g mails-agent mails config set api_key YOUR_KEY mails config set mailbox [email protected] mails config set worker_url https://api.mails0.com mails doctor # Download full reference (agent reads this automatically) curl -sL https://mails0.com/agent.md > ~/.claude/skills/mails-email.md # Quick test: receive and code workflows work first mails inbox mails code --to [email protected] --timeout 30

Paste this once in OpenClaw — installs, configures, and teaches your agent

# Install mails0 email for your agent ([email protected]) npm install -g mails-agent mails config set api_key YOUR_KEY mails config set mailbox [email protected] mails config set worker_url https://api.mails0.com mails doctor # Download full reference (agent reads this automatically) curl -sL https://mails0.com/agent.md > ~/.claude/skills/mails-email.md # Quick test: receive and code workflows work first mails inbox mails code --to [email protected] --timeout 30

Install and configure

npm install -g mails-agent mails config set api_key YOUR_KEY mails config set mailbox [email protected] mails config set worker_url https://api.mails0.com mails doctor # Try receive/code first. Hosted outbound can require warm-up. mails inbox mails inbox --query "verification" mails code --to [email protected] --timeout 30

Full CLI + API reference →

Install and use

pip install mails-agent from mails_agent import MailsClient client = MailsClient( api_url="https://api.mails0.com", token="YOUR_KEY", mailbox="[email protected]", ) # Inbox emails = client.get_inbox() # Wait for verification code code = client.wait_for_code(timeout=30)

Full Python + HTTP reference →

Add to your MCP config (Claude Desktop / Cursor / Windsurf)

{ "mcpServers": { "mails": { "command": "npx", "args": ["-y", "mails-agent-mcp@2.2.0"], "env": { "MAILS_API_URL": "https://api.mails0.com", "MAILS_API_KEY": "YOUR_KEY", "MAILS_MAILBOX": "[email protected]" } } } }

Full reference →

Agent start npm install -g mails-agent && mails bootstrap

Trust & controls

Four guarantees.

Contain the blast radius and preserve every message — even when the agent misbehaves.

01 / Isolation

Per-mailbox scoped keys

Every mailbox gets its own API key. A leaked or misused key can only touch the mailbox it was issued for — never your other mailboxes, your domain config, or your billing.

02 / Durability

Raw-first, zero loss

Every inbound email is persisted to R2 before any parsing or routing. If a parser, webhook, or agent ever crashes, the original message is still recoverable byte-for-byte.

03 / Guardrails

Rate limits & suppression

100 sends/day per mailbox (configurable when self-hosted) plus automatic bounce and complaint suppression. A runaway agent can't burn your domain reputation or drain your quota.

04 / Sovereignty

Your keys, your exit

Self-hosted on your own Cloudflare account. MIT licensed. Audit the code, rotate keys, pause a mailbox, or walk away anytime — no vendor lock-in.

Why mails0

Open source, on your infrastructure.

MIT licensed, self-hostable on Cloudflare, with agent-native tooling for inboxes, OTP codes, MCP, and browser-agent workflows.

mails0.com

$0self-hosted

Cloudflare free tier covers: 100k Worker requests/day · 10 GB R2 · 5 GB D1 · unlimited inbound email

Open source (MIT)

Self-hosted, your data

CLI + SDK + Agent Skills + MCP

Custom domains with DNS verification

Hosted alternatives

Usage-based pricing

Pay per seat, per mailbox, or per message. Data lives on vendor servers.

Closed source

Vendor-hosted, their servers

Generic APIs, limited agent-native tooling

Custom domain tiers vary

How it works

Three commands to first inbox workflow.

Bootstrap a receive-only mailbox, read the inbox, and wait for a verification code. Same surface in CLI or MCP, with Python available for configured mailboxes.

Step 1

Bootstrap

$ mails bootstrap Temporary mailbox ready: [email protected]

Step 2

Read

$ mails inbox \ --query "verification" Found: Your login code is 847291

Step 3

Extract

$ mails code \ --to [email protected] Waiting for code... 847291

▶ Try the interactive demo →

Capabilities

Everything an agent needs.

Send, receive, search, extract, observe. One API, six first-class primitives.

01

Send and receive

Full email with CC/BCC, In-Reply-To threading, and attachments. Receive via Cloudflare Email Routing with raw-first R2 persistence.

02

Search and extract

Full-text search (FTS5) across inbox. Automatic verification code extraction for EN, ZH, JA, and KO. Long-poll until code arrives.

03

Real-time events

Webhooks with HMAC-SHA256 signature verification. SSE streams for message.received. Auto-labeling: newsletter, notification, code, personal.

04

Structured extraction

Extract orders, shipping, calendar events, and receipts from emails. Deterministic parsers — no LLM cost, no hallucinations.

05

Visual dashboard

Inspect every mailbox, message, and webhook delivery in the built-in console. Debug deliverability or hand a mailbox to a non-developer — no DB client required.

06

Custom domains & deliverability

Bring any domain. mails0 guides you through SPF, DKIM, and MX verification so inbound routing and outbound deliverability just work — on your own Cloudflare account.

Integrations

Install once, use everywhere.

One API key. Four ways to use it: CLI, Python SDK, MCP server, and agent-native skill packs.

Recommended start

Command-line email for any agent runtime.

Create a temporary mailbox, read messages, and wait for verification codes from the same terminal surface your agent already uses.

$npm install -g mails-agent && mails bootstrap

CLI reference →

mails0 CLI

mails bootstrap
mails inbox --query "verification"
mails code --timeout 30

SDK workflow

Typed Python access for scripts and services.

Use the hosted API or your own deployment from workers, notebooks, background jobs, and agent tooling.

$pip install mails-agent

Python SDK docs →

python

from mails_agent import MailsClient
client = MailsClient("mk_...")
code = client.wait_for_code(
    "[email protected]",
    timeout=60,
)

Agent-native

Drop-in skill files for coding agents.

Teach Claude Code, OpenClaw, Cursor, and similar agents how to use a real inbox without custom glue code.

$npx mails-skills

View skill.md →

agent skill

# Or install via OpenClaw:
clawhub install mails-for-agent
# Or manually:
curl -sL mails0.com/skill.md \
  > ~/.claude/skills/email.md

Tool server

MCP tools for inbox, search, send, and codes.

Expose mails0 as a standard tool server for Claude Desktop, Cursor, Windsurf, and other MCP clients.

$npx mails-agent-mcp

MCP setup →

mcp server

# Works with Claude Desktop, Cursor, Windsurf
# Call get_inbox or wait_for_code immediately
# The first safe inbox is created automatically

Implementation library

Choose the path that matches the job.

Product capabilities, audience workflows, fair vendor comparisons, implementation guides, and direct answers share one evidence-backed content system.

8 product capabilities

Features

Understand the mailbox, extraction, MCP, search, event, and self-hosting primitives before choosing an interface.

Agent mailboxes Verification code extraction Email MCP server Attachments and extraction

8 audience workflows

Built for

Map email infrastructure to the operating model of agents, coding tools, QA teams, browser automation, and Cloudflare deployments.

AI agents Coding agents QA engineers Platform engineers

13 sourced comparisons and rankings

Compare

Compare product scope, operating model, and tradeoffs using current official documentation instead of invented feature claims.

mails0 vs Resend mails0 vs MailSlurp mails0 vs Gmail API Best email APIs for AI agents Best email testing tools

14 implementation guides

Guides

Build production-shaped workflows for agent identity, Playwright verification, MCP tools, Cloudflare, security, and evaluation.

Give an AI agent an email address Automate verification with Playwright Self-host on Cloudflare Defend against email prompt injection

15 direct answers

Questions and answers

Get concise answers designed for search and answer engines, followed by implementation detail, limits, security, and next steps.

How can an AI agent receive email? What is an email MCP server? Agent mailbox vs disposable email Best email API for AI agents?

FAQ

Questions.

What is mails0?

mails0 is open-source email infrastructure for AI agents. It lets agents send, receive, search emails, and extract verification codes programmatically. Deploy on your own domain with Cloudflare Workers (free tier).

What's the difference between mails0, mails-agent, and the mails CLI?

mails0 is the product. mails-agent is the npm and PyPI package that ships the SDK and CLI (npm install -g mails-agent or pip install mails-agent). mails is the CLI binary you run from your terminal. They all refer to the same thing.

How do I give my AI agent an email address?

Install with npm install -g mails-agent and run mails bootstrap for a hosted receive-only mailbox. Use mails claim <name> when a human is ready to approve a permanent identity. For production outbound email, self-host on Cloudflare with your own domain. For MCP clients, use npx mails-agent-mcp.

Can AI agents extract verification codes from emails?

Yes. mails0 automatically extracts 4-8 character verification codes from email subject and body. It supports English, Chinese, Japanese, and Korean. Use mails code --to [email protected] to wait for a code.

What are the send limits?

100 sends/day per mailbox by default, reset at UTC midnight. Self-hosted deployments can raise the cap via the DAILY_SEND_LIMIT env var. Inbound email has no cap. See Limits & quotas.

How does outbound deliverability work?

Outbound uses Resend, which manages SMTP infrastructure and IP reputation. You bring and verify your sending domain with SPF and DKIM. Inbound goes directly through Cloudflare Email Routing — no third party.

Is mails0 free and open source?

Yes. mails0 is MIT licensed and fully open source on GitHub. The Cloudflare free tier covers Workers, D1 database, R2 storage, and Email Routing, so there is no cost to self-host.

How is mails0 different from AgentMail?

AgentMail is a managed agent inbox service. mails0 is MIT-licensed and can run in your own Cloudflare account. Choose AgentMail when you want vendor-operated infrastructure; choose mails0 when source access, self-hosting, data control, and deployment ownership matter. See full comparison.