Developer APIUpdated 2026-05-25
API Tokens And Scopes
Create, scope, rotate, and verify Mailbase API tokens for workspace-safe backend integrations.
Canonical: /docs/api-tokens
Create A Token
- Open Settings, then Developer API.
- Choose a token name, select only the scopes your integration needs, and optionally set an expiry date.
- Save the raw token immediately. Mailbase stores a hash and will not show the raw value again.
- Put the token in a backend secret manager. Never ship it to browser code or mobile clients.
Verify The Token
Call /api/v1/me from staging or CI to confirm the token is valid, still unexpired, and bound to the intended workspace.
curl https://mailbase.example.com/api/v1/me \
-H "Authorization: Bearer mb_live_..."Scopes
Every external API request is checked against the token scopes and the token's workspace. A token cannot cross into another workspace.
| Scope | Allows |
|---|---|
| email:send | Send transactional email through the workspace sender setup. |
| campaigns:read | List campaigns and delivery stats. |
| audiences:read | List audiences and contact counts. |
| audiences:write | Create audiences and import contacts. |
| contacts:read | Read contact profiles and suppression status. |
| contacts:write | Create, update, suppress, or resubscribe contacts. |
| events:read | Read delivery, engagement, and reply events. |
| events:write | Record behavioural contact events, including conversion value. |
| templates:read | Read email templates. |
| templates:write | Create and update email templates. |
| webhooks:write | Create and manage outgoing webhook endpoints. |
| analytics:read | Read analytics endpoints as they are added. |
Rotation And Revocation
- Create a replacement token before removing the old token from your production secret store.
- Deploy the new secret, verify /api/v1/me, then revoke the old token in Settings.
- Use expiry dates for temporary automations, tests, and vendor handoffs.
- Rate-limit headers are returned on API responses so backend jobs can back off safely.