Authentication

Every request to the BoostMail API authenticates with a bearer API key. The generated API reference shows the bearer scheme on each endpoint; this guide explains how it works in depth.

Send the key as a bearer token

Put your key in the Authorization header on every request:

Authorization: Bearer bm_live_...

For example:

curl https://api.boostmail.app/v1/subscribers \
  -H "Authorization: Bearer bm_live_..."

Key format

A key has two parts: the prefix bm_live_ and a 43-character base64url random segment, 51 characters in total. The live segment marks a live key. A test variant is reserved for a future test mode, so every key you mint today is a live key.

Minting a key

Keys are minted in the BoostMail dashboard only. There is no /v1 endpoint for creating, listing, or rotating a key.

From the dashboard: Account > API Keys > Create key. Name the key, choose its scopes, and copy the secret. BoostMail shows the secret once, at creation time, and never displays it again. If you lose it, create a new key and update your integration.

Scopes

A key carries one or more scopes. An endpoint accepts a request only when the key has the scope that endpoint requires.

Scope	Grants
`subscribers:read`	Read subscribers
`subscribers:write`	Create and update subscribers
`segments:read`	Read segments
`campaigns:read`	Read campaigns
`campaigns:write`	Create and update campaigns
`campaigns:send`	Send a campaign
`templates:read`	Read templates
`transactional:send`	Send a transactional email
`stats:read`	Read stats

Authentication errors

Status	Code	When
`401`	`invalid_credential`	The key is missing, invalid, revoked, or suspended.
`403`	`insufficient_scope`	The key is valid but lacks the scope the endpoint requires.

A 401 response:

{
  "error": {
    "code": "invalid_credential",
    "message": "invalid_credential"
  }
}

A 403 response:

{
  "error": {
    "code": "insufficient_scope",
    "message": "insufficient_scope"
  }
}

See the Errors guide for the full error envelope and status code table.