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.

Header
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 with test_mode: true.
  • Two recipient addresses let you rehearse failures:
RecipientResult
bounce@simulator.mailforge.testThe email ends as bounced.
fail@simulator.mailforge.testThe email ends as failed.
Any other addressThe 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.

PermissionAllows
emails:sendSend email, send batches, cancel scheduled email
emails:readList and read email, delivery status and analytics
templates:readList and preview templates
templates:writeCreate, change and delete templates
domains:readList domains and their DNS records
domains:writeAdd domains, run DNS verification, change tracking settings
providers:readList provider routes
providers:manageAdd, change, test and delete provider routes
webhooks:readList webhook endpoints and their deliveries
webhooks:manageCreate, change, test and delete webhook endpoints, show the signing secret
suppressions:readList the suppression list
suppressions:manageAdd and remove suppressed addresses
apikeys:readList API keys
apikeys:manageCreate and revoke API keys
inbound:readList received email
automations:readList automations
automations:manageCreate and delete automations

New keys default to emails:send and emails:read, which is all a backend that only sends mail needs.

Wildcards

PatternMeaning
emails:sendOne action in one area
emails:*Every action in one area
*Everything. Workspace owners have this.
403 response
{
  "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.