# MailReach API

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

You can use the API from any language or tool. All you need is an HTTP client. Use it to run email spam tests, connect and manage inboxes for warming and monitoring, pull deliverability statistics, and automate every workflow available in the MailReach app.

Tip

**Setting up warming or monitoring?** Start with [Connect an inbox](/connect-account) to add your mailboxes, then enable warming from the account settings. Use [Account statistics](/account-stats) to pull deliverability data once they're live.

Tip

**Just getting started?** Follow the [one-time spam test guide](/spam-test) to make your first API call in under five minutes. No extra setup required beyond your API key.

## Before you begin

* You need a **MailReach account** and at least one project. Sign up at [mailreach.co](https://www.mailreach.co).
* Your **API key** lives on the **Settings** tab of your project. Treat it like a password: keep it out of source control and client-side code.
* The API is **free to call**. You are only billed for platform usage (spam test credits and warming seats).

## Base URL

All API endpoints share the same base:

```plaintext
https://api.mailreach.co/api/v1
```

## Authentication

Every request must include your API key in the `X-Api-Key` header, prefixed with `Bearer`:

```http
X-Api-Key: Bearer YOUR_API_KEY
```

Requests with a missing or invalid key return `401 Unauthorized`.

## Requests

The API accepts JSON. Always set `Content-Type: application/json` on requests that include a body:

```http
POST https://api.mailreach.co/api/v1/spam_tests
X-Api-Key: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "seedlist": 1
}
```

## Responses

All responses are JSON. A successful request returns a `2xx` status code and a JSON body. An error returns a `4xx` or `5xx` status code and a JSON body with a `message` field:

```json
{
  "message": "Invalid API key"
}
```

## HTTP status codes

| Code  | Meaning                                                                               |
| ----- | ------------------------------------------------------------------------------------- |
| `200` | Success                                                                               |
| `201` | Resource created                                                                      |
| `400` | Bad request: malformed JSON or missing required field                                 |
| `401` | Unauthorized: API key missing or invalid                                              |
| `403` | Forbidden: the key does not have access to this resource                              |
| `404` | Not found                                                                             |
| `422` | Unprocessable: the request is valid but cannot be acted on (e.g. duplicate, conflict) |
| `429` | Too many requests: back off and retry                                                 |
| `5xx` | Server error: retry with exponential backoff                                          |

## Errors

Errors always return a JSON body. The `message` field is human-readable and safe to surface in logs.

```json
{
  "message": "Account not found"
}
```

Some `422` responses include additional fields with more detail about what failed. Check the [API reference](/api) for the shape of each endpoint's error response.

## Idempotency

The API does not currently support idempotency keys. To avoid duplicate resources, check for an existing one before creating a new one, or use the response `id` to update rather than re-create.

## Pagination

Endpoints that return lists support `page` and `per_page` query parameters. Results are returned in descending creation order. Check the [API reference](/api) for the default and maximum page sizes per endpoint.

## Pricing

**The API itself is free.** You are only billed for what you use on the platform:

| Feature              | Billing                             |
| -------------------- | ----------------------------------- |
| Warming & Monitoring | Per connected inbox (seat), monthly |
| Spam Checker         | Per test run (one credit per test)  |

See [mailreach.co/pricing](https://www.mailreach.co/pricing) for the full breakdown.

## Next steps

* [One-time spam test](/spam-test): create a test, send the email, fetch the placement report.
* [Automated spam tests](/automated-test): schedule recurring inbox placement checks from a connected inbox.
* [Connect an inbox](/connect-account): IMAP/SMTP or OAuth for Gmail and Outlook, including batch workspace import.
* [Account statistics](/account-stats): pull daily time-series data to build your own deliverability dashboard.
* [Webhooks & Alerts](/webhooks): get notified in real time when something changes on an account or test.
* [MCP: AI assistants](/mcp): connect Claude, ChatGPT, Claude Code or Cursor to your project and let it run tests and manage mailboxes for you.
* Browse the full endpoint reference under **MailReach API** in the sidebar.
