Getting Started

Authentication

Authenticate every API request with a Bearer API key.

The MailBlastr API authenticates with an API key sent as a Bearer token. Keys are created in the dashboard under API Keys — see Create an API key. The full key is shown once at creation and stored only as a hash afterward.

Base URL

The API is built on REST principles and is served over HTTPS only — plain HTTP is not supported. Every request goes to the same base URL:

https://www.mailblastr.com/api

Authorization header

Add an Authorization header whose value is Bearer followed by your API key:

Authorization: Bearer mb_xxxxxxxxx

Treat API keys like passwords. Never commit them or expose them in client-side code — call the API from your server.

User-Agent header

Every API request must also include a User-Agent header. Requests without one are rejected with a 403, even when the API key is valid. Most HTTP clients set this automatically, but if you build requests by hand, set it explicitly:

User-Agent: my-app/1.0

If you get a 403 despite a valid API key, a missing User-Agent header is the most likely cause.

Permissions

Each key has a permission level:

Permission	Can do
full_access	Send email and manage resources (domains, audiences, contacts, campaigns).
sending_access	Send email only. Cannot create, update, or delete domains, audiences, contacts, or campaigns.

A sending_access key is the safest choice for a server that only needs to send transactional email. See Create an API key.

Neither permission covers API keys themselves. Creating a key, changing its permission or domain restriction, and revoking it are dashboard-only actions: POST /api-keys, PATCH /api-keys/:id, and DELETE /api-keys/:id refuse every API-key caller with 403 dashboard_only, whatever its permission. Sign in to the dashboard to manage keys. This is a breaking change — if you previously automated those three calls with a full-access key, that automation now fails and the steps must be done in the dashboard.

Rate limit

Rate limits are enforced over 60-second windows, per client IP — not per key or per team: roughly 30 requests per minute on the send endpoints, 20 per minute on expensive endpoints (such as AI and support), and 120 per minute on general public endpoints. There is no separate burst allowance, and requests from multiple services behind the same address count together. Exceeding a limit returns a 429. See Account quotas and limits.

Errors

A missing key returns 401 missing_api_key; an invalid or revoked key returns 403 invalid_api_key; a key without the required permission returns 401 restricted_api_key; an API key calling a dashboard-only endpoint returns 403 dashboard_only; a missing User-Agent returns 403. See Errors.