API keys and scopes
The API authenticates with a bearer key:
Authorization: Bearer mc_live_…Keys are issued in Workspace settings → API keys by an Owner or Admin. The plaintext is shown once at creation. mailcatchr stores only a hash, so a lost key has to be replaced.
Scopes
Section titled “Scopes”A key carries two scopes, fixed when it is issued:
- Mailboxes: all mailboxes in the workspace (including ones created later), or an explicit set.
- Authenticators: all TOTP authenticators, or an explicit set.
Scopes cannot be edited. To change what a key can see, issue a new key and revoke the old one. That keeps the audit trail simple: a key only ever did what it was scoped for at issue time.
Out of scope means 404
Section titled “Out of scope means 404”A request for a resource the key cannot see answers 404, never 403. A key cannot learn that a sibling mailbox exists by probing for it. The same applies to listing: GET /v1/mailboxes returns only the mailboxes in scope.
Keys per workspace
Section titled “Keys per workspace”| Plan | Active keys |
|---|---|
| Free | 5 |
| Business | 100 |
Revoked keys do not count against the limit.
Rate limits and idempotency
Section titled “Rate limits and idempotency”- 100 requests per minute per key, and 1,000 per minute per workspace. Over the limit the API answers
429with aRetry-Afterheader. - POST endpoints accept an
Idempotency-Keyheader. A replay with the same key within 24 hours returns the original response without running again. Use it for sends.
Keeping keys out of the repository
Section titled “Keeping keys out of the repository”Store the key in your CI system’s secret store and read it from an environment variable. The guides use MAILCATCHR_API_KEY throughout. See GitHub Actions.