Authentication
Authenticate with scoped API keys and give each key only the permissions it needs.
Bearer API keys
Send your API key in the Authorization header of every request. Requests without a valid key get 401 Unauthorized.
Authorization: Bearer mf_live_Zk3vP0aQ...curl https://mail.example.com/api/v1/emails \
-H "Authorization: Bearer $MAILFORGE_API_KEY"Keys are created in the dashboard or with the API keys endpoint. A key belongs to one workspace and can only read and write that workspace's data.
Test mode
A key is created in live or test mode, which sets its prefix: mf_live_ or mf_test_. An email sent with a test key runs through the whole pipeline (validation, queue, status, events, webhooks) but is never handed to a mail server. Nobody receives anything.
- Test emails need no verified domain and do not count against the monthly quota.
- The response contains
testMode: true, and the email is stored withtest_mode: true. - Two recipient addresses let you rehearse failures:
| Recipient | Result |
|---|---|
bounce@simulator.mailforge.test | The email ends as bounced. |
fail@simulator.mailforge.test | The email ends as failed. |
| Any other address | The email ends as sent. |
Permissions
Every key carries a list of permissions. Each endpoint requires exactly one. A request with a key that lacks it gets 403 with the missing permission in the message.
| Permission | Allows |
|---|---|
emails:send | Send email, send batches, cancel scheduled email |
emails:read | List and read email, delivery status and analytics |
templates:read | List and preview templates |
templates:write | Create, change and delete templates |
domains:read | List domains and their DNS records |
domains:write | Add domains, run DNS verification, change tracking settings |
providers:read | List provider routes |
providers:manage | Add, change, test and delete provider routes |
webhooks:read | List webhook endpoints and their deliveries |
webhooks:manage | Create, change, test and delete webhook endpoints, show the signing secret |
suppressions:read | List the suppression list |
suppressions:manage | Add and remove suppressed addresses |
apikeys:read | List API keys |
apikeys:manage | Create and revoke API keys |
inbound:read | List received email |
automations:read | List automations |
automations:manage | Create and delete automations |
New keys default to emails:send and emails:read, which is all a backend that only sends mail needs.
Wildcards
| Pattern | Meaning |
|---|---|
emails:send | One action in one area |
emails:* | Every action in one area |
* | Everything. Workspace owners have this. |
{
"error": "Forbidden: missing capability \"domains:write\"",
"code": "missing_capability"
}How keys are stored
MailForge stores an HMAC-SHA256 hash of each key, never the key itself. The full key is returned once when you create it. If you lose it, revoke it and create a new one. Listing keys shows the first 16 characters so you can recognise a key, plus the time it was last used.