Authentication

All API requests to mails-agent require a Bearer token in the Authorization header. There are two types of API keys, each with different scopes and use cases.

Bearer Token Authentication

Include your API key in every request:

curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  https://mails-worker.genedai.workers.dev/v1/me

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

API Key Types

Type	Prefix	Scope	Use Case
Full-access	`mk_`	All mailboxes, all endpoints	Server-side admin, CI/CD, self-hosted deployments
Mailbox-scoped	`mk_`	Single mailbox only	Per-agent keys, client-side usage, least-privilege access

Full-access Keys

Full-access keys (mk_ prefix) can operate on any mailbox in your account. They can create and delete mailboxes, manage domains, list all mailboxes, and access any mailbox's inbox.

# Full-access key — can specify any mailbox
curl -s -H "Authorization: Bearer mk_abc123..." \
  "https://mails-worker.genedai.workers.dev/v1/[email protected]"

Mailbox-scoped Keys

Mailbox-scoped keys (mk_ prefix) are bound to a single 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://mails-worker.genedai.workers.dev/v1/inbox"

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

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:

CLI: Run mails config to view your current key, or mails claim to create a new mailbox and receive a scoped key.
Dashboard: Navigate to Settings → API Keys in the web dashboard to create and manage keys.
Self-hosted: Set the AUTH_TOKEN environment variable in your Cloudflare Worker configuration.

Key Permissions Matrix

Endpoint	Full-access	Mailbox-scoped
`GET /v1/inbox`	Any mailbox	Own mailbox only
`POST /v1/send`	Any from address	Own mailbox as sender only
`GET /v1/code`	Any mailbox	Own mailbox only
`GET /v1/search`	Any mailbox	Own mailbox only
`GET /v1/events`	Any mailbox	Own mailbox only
`POST /v1/domains`	Yes	No
`GET /v1/me`	Yes	Yes
`GET /v1/stats`	All mailboxes	Own mailbox only

Security Best Practices

Use mailbox-scoped keys whenever possible. Follow the principle of least privilege. If an agent only needs access to its own mailbox, give it a scoped key.
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://mails-worker.genedai.workers.dev/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.