Mailboxes

A mailbox is the core identity in mails-agent. Each mailbox is a unique email address that can send and receive messages, and is associated with an API key for authentication.

Address Format

Mailbox addresses follow standard email format. The domain depends on your setup:

Setup	Format	Example
Hosted (default)	[email protected]	[email protected]
Self-hosted (custom domain)	[email protected]	[email protected]

On the hosted service, you can bootstrap a random temporary address or claim a permanent named address under mails0.com. With a self-hosted deployment, you can use any domain you have added to Cloudflare Email Routing.

Creating a Mailbox

Automatic temporary mailbox

For agent onboarding and verification-code workflows, bootstrap a random 72-hour receive-only mailbox. It requires no browser approval, stores the key locally, and never prints the key:

mails bootstrap
mails inbox
mails code --timeout 30

For MCP clients, start mails-agent-mcp without credentials and call create_temporary_mailbox. Temporary mailboxes cannot send, manage attachments or webhooks, add domains, or create more mailboxes.

Permanent named mailbox

The mails claim command creates a permanent mailbox-scoped key after human browser approval:

# Claim [email protected]
mails claim my-agent

This opens a browser for human approval. In headless environments, it prints a URL for the human to confirm. After approval, the CLI saves the API key and mailbox address to ~/.mails/config.json.

Headless agents

Do not automate the permanent claim confirmation endpoint. Use POST /v1/bootstrap through the official CLI or MCP server so idempotency, local secret storage, expiry, and abuse limits are applied consistently. Upgrade with mails claim <name> only when a human is ready to approve a permanent identity.

Mailbox States

Every mailbox has a status field (stored in the auth_tokens table) that controls whether it can process requests:

Status	Description	API behavior
active	Mailbox is fully operational (default)	All endpoints work normally
paused	Mailbox is temporarily suspended	All endpoints except mailbox management return 403 with {"error": "Mailbox is paused"}

When a mailbox is paused, the mailbox management endpoints (GET /v1/mailbox, PATCH /v1/mailbox/pause, PATCH /v1/mailbox/resume) remain accessible so you can check status and resume.

Pause and Resume

You can pause a mailbox to temporarily disable all operations (sending, receiving, searching), and resume it later.

Pause a Mailbox

curl -s -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.mails0.com/v1/mailbox/pause"

{
  "mailbox": "[email protected]",
  "status": "paused"
}

Resume a Mailbox

curl -s -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.mails0.com/v1/mailbox/resume"

{
  "mailbox": "[email protected]",
  "status": "active"
}

Mailbox Info

Returns the current mailbox status, webhook URL, and creation date:

curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.mails0.com/v1/mailbox"

{
  "mailbox": "[email protected]",
  "status": "active",
  "webhook_url": "https://your-server.com/webhook",
  "created_at": "2026-03-15T10:00:00Z"
}

Per-Mailbox Settings

Each mailbox can have its own webhook URL configured. Use PATCH /v1/mailbox to set or update it:

curl -s -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.mails0.com/v1/mailbox" \
  -d '{"webhook_url": "https://your-server.com/webhooks/mails"}'

The webhook_url is stored in the auth_tokens table and is used by the webhook system to deliver real-time notifications for this mailbox. See Webhooks for details on event types and signature verification.

CLI Commands

Command	Description
mails bootstrap	Create or reuse a random 72-hour receive-only mailbox
mails claim <name>	Claim permanent [email protected] after human approval
mails config	View current mailbox and API key configuration
mails doctor	Verify mailbox exists, API is reachable, and send is configured
mails webhook set <url>	Set webhook URL for the current mailbox
mails webhook list	View current webhook configuration