API Reference

Create API key

POST /api-keys — dashboard-only. Keys are generated in the dashboard; an API key cannot mint a key.

POST/api-keys

Dashboard-only. API keys are generated on the website. A request authenticated with an API key is refused with 403 dashboard_only — "API keys can only be created, edited and revoked from the MailBlastr dashboard, not with an API key." — no matter what permission that key holds. Create keys from the dashboard under API Keys.

This is a breaking change. Automation that used to mint keys with a full_access key now receives 403 dashboard_only and must be replaced by a person creating the key in the dashboard and storing it in your secret manager. The official SDKs deliberately expose no method for this endpoint.

Creates a new API key and returns the full mb_... token once. Only the hash and prefix are stored, so copy the token immediately. The reference below describes the request the dashboard makes on your behalf with a signed-in session — it is not callable with an API key.

Body parameters

namestringrequired

A label for the key. Maximum 50 characters.

permissionfull_access | sending_accessoptional

The access level. full_access (default) can create, delete, get, and update any resource; sending_access can only send emails.

domain_idsstring[]optional

Restrict the key to send only from these domains — enforced on every send surface (POST /emails, batch, campaign sends, and receiving reply/forward). Only valid with sending_access — full-access keys always work across all your domains. Omit (or send an empty array) to allow all domains.

domain_idstringoptional

Legacy single-domain form of domain_ids. Provide one or the other, not both.

Response

For the dashboard session, the created key is returned with its one-time token:

{
  "id": "1042",
  "object": "api_key",
  "token": "mb_AbC123dEf456GhI789jKl012mNoPqRs",
  "domain_id": null,
  "domain_ids": null
}

Response to an API-key caller

{
  "statusCode": 403,
  "name": "dashboard_only",
  "message": "API keys can only be created, edited and revoked from the MailBlastr dashboard, not with an API key."
}

The token is shown exactly once. Errors: dashboard_only (403) for every API-key caller — this check runs before any validation; missing_required_field if name is absent; validation_error if permission is not full_access or sending_access, if both domain_id and domain_ids are provided, if a domain restriction is combined with full_access, if domain_ids references a domain that is not yours, or if domain_ids contains more than 50 domains. Two 429s guard key sprawl: rate_limit_exceeded — "Max 5 keys per hour. Try again later." — once you have created 5 keys in the last hour, and max_active_keys — "Max 20 active keys. Revoke unused keys first." — once 20 unrevoked keys already exist on the account.