API tokens and scopes
Create, scope, rotate, and verify Mailbase API tokens for workspace-safe backend integrations.
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. API tokens are for servers and CI; on your own machine, mailbase login signs the CLI in through the browser with no token to handle.
- 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.
A token is never worth more than the person who created it: each request also checks that person's current workspace role. Every endpoint that changes data (sending mail, contacts, audiences, events) needs a creator who can write in the workspace, so a token made by a Viewer, Billing or Developer member is read-only there. If they are demoted, the token loses what the new role cannot do; if they leave the workspace, it stops working.
| 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. |
| prospecting:read | Read prospecting targets, the prospect pool, drafts and sequence state. |
| prospecting:write | Create targets, approve or reject prospect drafts, and pause or resume the sequence. |
| analytics:read | Read workspace, deliverability and prospecting analytics and the sent-email log. |
| campaigns:write | Create, edit, duplicate and delete draft campaigns and their A/B variants. |
| campaigns:send | Launch, schedule, cancel and test-send campaigns. |
| workflows:read | Read automation workflows and their enrollments. |
| workflows:write | Create, edit, pause and delete workflows (as drafts). |
| workflows:send | Activate workflows, enroll contacts and fire workflow events — these email people. |
| inbox:read | Read reply threads, notes, the pipeline and follow-ups. |
| inbox:write | Update reply threads (status, tags, notes, pipeline stage) and schedule or cancel follow-ups. |
| forms:read | Read signup forms and subscription topics. |
| forms:write | Create, edit and delete signup forms and subscription topics. |
| sending:read | Read sending domains, their DNS health, sender addresses and connected mailboxes. |
| sending:write | Connect, verify and remove domains, and manage sender addresses and mailboxes. |
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.