API Reference

The MailBlastr REST API: base URL, authentication, content type, idempotency, rate limits, and error format.

The MailBlastr API is organized around REST. It has predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and verbs.

Base URL

https://www.mailblastr.com/api

All requests are made over HTTPS. The resources are mounted at the root: /emails, /domains, /audiences, /campaigns, /api-keys.

Authentication

Authenticate with your API key as a Bearer token on every request. See Authentication.

Authorization: Bearer mb_xxxxxxxxx

Official SDKs

Most endpoints in this reference show examples for the Node.js, Python, Ruby and PHP packages alongside raw cURL, plus a CLI tab wherever the CLI ships that command. The Go, Rust, Java and .NET tabs show the SDK for the core operations. Where an endpoint has no SDK mapping for a language, that tab falls back to an equivalent plain-HTTP request in the same language, so every sample is runnable as printed. Pick your language from the tabs on any request sample.

Language	Package	Install
Node.js	`mailblastr`	`npm install mailblastr`
Ruby	`mailblastr`	`gem install mailblastr`
PHP	`mailblastr/mailblastr`	`composer require mailblastr/mailblastr`
Python	`mailblastr`	`pip install mailblastr`
Go	`github.com/shekhu10/mailblastr-sdks/mailblastr-go/v5` (package `mailblastr`)	`go get github.com/shekhu10/mailblastr-sdks/mailblastr-go/v5`
Rust	`mailblastr`	`cargo add mailblastr`
Java	`com.mailblastr:mailblastr`	`implementation 'com.mailblastr:mailblastr:5.0.0'`
.NET	`Mailblastr`	`dotnet add package Mailblastr`
CLI	`mailblastr-cli`	`npm install -g mailblastr-cli`

Content type

Send request bodies as JSON with Content-Type: application/json. Responses are always JSON.

User-Agent

All API requests must include a User-Agent header. Requests without it are rejected with a 403 status code. If you are making direct HTTP requests, 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 likely cause.

Response codes

MailBlastr uses standard HTTP codes: 2xx for success, 4xx for user-related failures, and 5xx for infrastructure issues.

Status	Description
`200`	Successful request.
`400`	Check that the parameters were correct.
`401`	The API key used was missing.
`402`	A plan limit was reached (for example the domain cap). Upgrade to continue.
`403`	The API key used was invalid.
`404`	The resource was not found.
`429`	The rate limit or an account quota was exceeded.
`5xx`	Indicates an error with MailBlastr servers.

Versioning

There is currently no versioning system in place. Versioning via calendar-based headers is planned for the future.

Pagination

Some list endpoints support cursor-based pagination to browse large datasets efficiently.

Idempotency

POST /emails and POST /emails/batch accept an optional Idempotency-Key header so a retried send is not processed twice. Other mutating endpoints ignore the header — a retry there creates a second resource. See Idempotency keys.

Idempotency-Key: <your-unique-key>

Rate limits

The send endpoints (POST /emails and the transactional send API) are rate-limited per client IP to blunt bursts. When you exceed the send rate the response is a 429 rate_limit_exceeded — read the ratelimit-* and retry-after headers and back off accordingly. Other endpoints are not subject to this per-request cap; sustained volume is governed by your account quotas instead (see Usage limits).

Errors

Errors use standard HTTP status codes and a consistent JSON body. See the full error reference.

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`to` must contain between 1 and 50 recipients."
}