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 to add your mailboxes, then enable warming from the account settings. Use Account statistics to pull deliverability data once they're live.

Tip

Just getting started? Follow the one-time spam test guide 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.
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:

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

Authentication

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

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:

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:

{
  "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.

{
  "message": "Account not found"
}

Some 422 responses include additional fields with more detail about what failed. Check the API reference 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 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 for the full breakdown.

Next steps

One-time spam test: create a test, send the email, fetch the placement report.
Automated spam tests: schedule recurring inbox placement checks from a connected inbox.
Connect an inbox: IMAP/SMTP or OAuth for Gmail and Outlook, including batch workspace import.
Account statistics: pull daily time-series data to build your own deliverability dashboard.
Webhooks & Alerts: get notified in real time when something changes on an account or test.
Browse the full endpoint reference under MailReach API in the sidebar.

One-Time Spam Test