API keys

Every request to /v1 and to the MCP server carries a key as Authorization: Bearer letr_.... You create keys in the dashboard; the secret is shown once.

Permissions

• sending_access, the default for new keys, sends with POST /v1/emails and POST /v1/emails/batch and on the emails this key sent reads them with GET /v1/emails/{id}, their content with GET /v1/emails/{id}/content and attachments with GET /v1/emails/{id}/content/attachments/{index}, and cancels a scheduled one with POST /v1/emails/{id}/cancel. Nothing else.
• read_only may call every GET under /v1: emails, usage, metrics, domains, webhooks and suppressions. No sending, no changes.
• full_access may call everything under /v1. On top of reading, it sends, adds, verifies and removes domains, changes, deletes and tests webhook endpoints, and removes suppressions.

A request outside the key's permission answers 403 insufficient_permission. A domain, webhook endpoint or suppression of another account answers 404 not_found, like one that does not exist. The API reference names the permission of every endpoint.

Limit a key to domains

A sending_access key can be limited to up to 20 sending domains of your account. It may then only send from those; any other from-domain answers 403 domain_not_allowed. Without a limit it may use every verified domain. Give agents and single services a key limited to one domain.

Roll a key

Rolling replaces a key with a new one with the same name, permission and domains. Choose how long the old key keeps working: now, 1 hour, 24 hours or 7 days. Deploy the new key within that time and nothing fails. The roll itself cancels, right away, the scheduled emails the old key created that are due after its grace period; those due before stay. Schedule the cancelled ones again with the new key and a new Idempotency-Key: the old one would replay the cancelled email. A replacement sending_access key has a new ID and does not read the emails the old key sent; a read_only or full_access key reads them all. After the grace period the old key answers 401. A key that is already being replaced cannot be rolled again (422 api_key_expiring); roll its successor instead. Revoking a key stops it at once: open SMTP sessions using it stop at their next message, and the scheduled emails it created are cancelled.

No key manages keys

No API key can list, create, roll or revoke API keys, whatever its permission; that needs a signed-in user in the dashboard. A leaked key therefore cannot create more keys or lock you out of the others.