# 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

```bash
https://api.mailblastr.com
```

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](https://www.mailblastr.com/docs/authentication).

```bash
Authorization: Bearer mb_xxxxxxxxx
```

## Official SDKs

Every endpoint in this reference shows examples for each official package — 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 | `mailblastr-go` | `go get github.com/shekhu10/mailblastr-sdks/mailblastr-go` |
| Rust | `mailblastr` | `cargo add mailblastr` |
| Java | `com.mailblastr:mailblastr` | Maven / Gradle |
| .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:

```bash
User-Agent: my-app/1.0
```

> **Note:** 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. |
| `403` | The API key used was invalid. |
| `404` | The resource was not found. |
| `429` | The rate limit 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

Mutating endpoints accept an optional `Idempotency-Key` header so a retried request is not processed twice. See [Idempotency keys](https://www.mailblastr.com/docs/emails/idempotency).

```bash
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](https://www.mailblastr.com/docs/api/limits)).

## Errors

Errors use standard HTTP status codes and a consistent JSON body. See the full [error reference](https://www.mailblastr.com/docs/api/errors).

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