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 claim an address under the mails0.com domain. With a self-hosted deployment, you can use any domain you have added to Cloudflare Email Routing.

Claiming a Mailbox

Via CLI

The mails claim command creates a new mailbox and returns a mailbox-scoped API key:

# 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.

Via API

For programmatic mailbox creation, use the claim API flow: POST /v1/claim/start to create a session, then POST /v1/claim/confirm to complete it.

# Step 1: Start a claim session
SESSION=$(curl -s -X POST -H "Content-Type: application/json" \
  "https://mails0.com/v1/claim/start" \
  -d '{"name": "my-agent"}' | jq -r '.session_id')

# Step 2: Confirm the claim
curl -s -X POST -H "Content-Type: application/json" \
  "https://mails0.com/v1/claim/confirm" \
  -d "{\"session_id\": \"$SESSION\"}"

This creates [email protected] and returns a mailbox-scoped API key.

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

PATCH/v1/mailbox/pause — Pause a mailbox

curl -s -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/mailbox/pause"

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

Resume a Mailbox

PATCH/v1/mailbox/resume — Resume a paused mailbox

curl -s -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/mailbox/resume"

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

Mailbox Info

GET/v1/mailbox — Get mailbox details

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

curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  "https://mails-worker.genedai.workers.dev/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:

PATCH/v1/mailbox — Update mailbox settings

curl -s -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://mails-worker.genedai.workers.dev/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 claim <name>`	Claim `[email protected]` and save the API key to config
`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