Authentication

All API requests to mails-agent, except POST /v1/bootstrap, require a Bearer token in the Authorization header. The server assigns each key a scope; the mk_ prefix does not imply elevated access.

Bearer Token Authentication

Include your API key in every request:

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

If the key is missing or invalid, the API returns 401 with {"error": "Unauthorized"}.

API Key Types

Type	Scope	Lifetime	Use Case
Provisional	`provisional`	72 hours	Automatic agent onboarding for receive, read, search, and verification codes
Mailbox-scoped	`mailbox`	Until revoked	One permanent mailbox, including outbound email and mailbox settings
Operator	`operator`	Deployment-managed	Private administration for a self-hosted deployment

Provisional Keys

mails bootstrap or the MCP create_temporary_mailbox tool creates an expiring receive-only mailbox. The key can read only that mailbox and cannot send, download attachments, manage domains or webhooks, create other mailboxes, or perform moderation.

npm install -g mails-agent
mails bootstrap
mails inbox
mails code --timeout 30

Mailbox-scoped Keys

Mailbox-scoped keys are bound to a single permanent mailbox at creation time. They can only send and receive email for their own mailbox. Any attempt to access another mailbox returns 403 Forbidden.

# Mailbox-scoped key — mailbox is implicit from the key
curl -s -H "Authorization: Bearer mk_xyz789..." \
  "https://api.mails0.com/v1/inbox"

# Trying to access another mailbox → 403
curl -s -H "Authorization: Bearer mk_xyz789..." \
  "https://api.mails0.com/v1/[email protected]"
# → {"error": "forbidden", "message": "Key not authorized for this mailbox"}

Operator Credentials

Operator access is never returned by hosted bootstrap or claim flows. It is reserved for deployment owners and is configured explicitly, such as with the self-hosted AUTH_TOKEN secret. Do not distribute an operator credential to an agent.

Key Format

API keys use the mk_ prefix followed by 64 hex characters, for a total of 67 characters:

# API key format (mk_ prefix + 64 hex chars = 67 chars total)
mk_5fbc897fa0380dc1875a5b9502ed316dbd5ad41dd1814b605fbc897fa0380dc1

# Mailbox-scoped key format
mk_8a3c12ef90b74d2e56f1a8c3d0e9b7f4a2c5d8e1f0b3a6c98a3c12ef90b74d2e

Getting Your API Key

You can obtain an API key in several ways:

Automatic temporary mailbox: Run mails bootstrap, or let an MCP client call create_temporary_mailbox. The key is stored locally and never printed or returned to the model.
Permanent mailbox: Run mails claim <name> and complete human approval in the browser.
Self-hosted operator: Set the AUTH_TOKEN Worker secret and keep it in a server-side secret manager.

Key Permissions Matrix

Capability	Provisional	Mailbox	Operator
Read inbox, email, code, search, threads, events, stats	Own mailbox	Own mailbox	Configured mailbox
Extract structured data	Own mailbox	Own mailbox	Configured mailbox
Send email	No	Own mailbox	Configured mailbox
Attachments, webhooks, custom domains	No	Own mailbox resources	Configured mailbox resources
Create or moderate mailboxes	No	No	Yes
Delete own mailbox	Yes	Yes	Yes

Security Best Practices

Start receive-only. Use a provisional key when an agent only needs signup email or verification codes, then upgrade deliberately.
Use mailbox-scoped keys for permanent agents. Never give an agent an operator credential.
Never expose keys in client-side code. API keys should live in environment variables or secret managers, never in frontend JavaScript or public repositories.
Rotate keys regularly. Delete old keys from the dashboard and issue new ones periodically. Revoked keys are rejected immediately.
Use environment variables. Store your key in MAILS_API_KEY and reference it in your application.
One key per agent. If you run multiple agents, give each its own mailbox-scoped key. If one is compromised, revoke it without affecting others.
Monitor usage. Use GET /v1/stats to detect unusual activity (unexpected send volume, unfamiliar recipients).
HTTPS only. The API enforces HTTPS. Never send API keys over unencrypted connections.

# Store key in environment variable
export MAILS_API_KEY="mk_8a3c12ef90b74d2e56f1a8c3d0e9b7f4a2c5d8e1f0b3a6c98a3c12ef90b74d2e"

# Reference in curl
curl -s -H "Authorization: Bearer $MAILS_API_KEY" \
  "https://api.mails0.com/v1/me"

Error Responses

Status	Response body	Meaning
`401`	`{"error": "Unauthorized"}`	Missing or invalid API key
`403`	`{"error": "Mailbox is paused"}`	The mailbox is paused. Resume it via `PATCH /v1/mailbox/resume` before making requests.