Unspam API.

Run the same checks the dashboard runs, from your own code: spam tests, inbox placement, client previews and recurring automatic tests. 29 endpoints across 6 areas, one bearer token, JSON in and JSON out.

POST /ext/v2/spam-check OpenAPI document

curl -X POST https://api.unspam.email/ext/v2/spam-check \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# returns the test id and the address to send to
{
  "id": "2Bl8rzTFN6VV",
  "inbox_address": "test-xyz@check.unspam.email"
}

# send your email to that address, then read the result
curl https://api.unspam.email/ext/v2/spam-check/2Bl8rzTFN6VV \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
{
  "score": 8.4,
  "spf": "pass",
  "dkim": "pass",
  "dmarc": "pass"
}

What the API covers.

29 endpoints in 6 groups, listed the way the API groups them. The full reference, with every parameter and response code, is the OpenAPI document.

Client Previews

4 calls

GET /client-preview-devices
GET /client-previews
POST /client-previews
GET /client-previews/{id}

Inbox Placement

4 calls

GET /inbox-placement
POST /inbox-placement
GET /inbox-placement/mailboxes
GET /inbox-placement/{id}

Automatic Testing: Senders

6 calls

GET /scheduled-test-senders
POST /scheduled-test-senders
GET /scheduled-test-senders/{id}
PUT /scheduled-test-senders/{id}
DELETE /scheduled-test-senders/{id}
POST /scheduled-test-senders/{id}/test-connection

Automatic Testing: Tests

9 calls

GET /scheduled-tests
POST /scheduled-tests
GET /scheduled-tests/{id}
PUT /scheduled-tests/{id}
PATCH /scheduled-tests/{id}
DELETE /scheduled-tests/{id}
POST /scheduled-tests/{id}/dispatch-now
GET /scheduled-tests/{id}/runs
GET /scheduled-tests/{id}/runs/{runId}

Spam Check

5 calls

GET /spam-check
POST /spam-check
GET /spam-check/{id}
GET /spam-check/{id}/heatmap
GET /spam-check/{id}/screenshots

Account

1 call

GET /status

What you can build with it.

Test before you ship

Start a spam check from a deploy step or a CI job, send the message your app really sends, and read the score before the campaign goes out.

Recurring inbox tests

Connect a sender once and let scheduled tests run on their own cadence, so inbox placement is checked on a schedule instead of only when somebody remembers.

Previews across real clients

Ask for client previews on a test you already ran and get one entry per device, each captured in a real client rather than simulated from the markup.

Results as JSON

Scores, authentication results, heatmaps and screenshots all come back as JSON, so they land in your own dashboard or your own alerts.

Where it fits.

Anything that already speaks HTTP can run these checks. These are the places the API usually lands, and the teams that get the most out of it.

Apps and pipelines it plugs into.

CI and deploy pipelines

Run a spam check as a build step and fail the deploy when the score drops, so a template edit cannot quietly cost you the inbox.

Your sending stack

The test receives a real message from your real path: SES, Postmark, SendGrid, Mailgun or your own SMTP, whatever already sends your email.

Internal dashboards

Scores, placement and authentication results come back as JSON, so they land in the dashboard your team already watches.

Alerting and on-call

Poll scheduled test runs from a cron job and alert whoever is on call when placement drops, before the open rate does.

Products that send email

Embed the checks in your own product on the White Label plan: an email builder or an agency platform can offer spam testing under its own brand.

AI assistants

Over MCP, the same jobs are tools an assistant can call, so a check can run in the middle of a conversation with no client code written.

Who gets the most out of it.

Agencies Run every client's deliverability from one account and report under your own brand. SaaS Password resets, magic links and billing emails are product surface: an email nobody sees is an incident. Ecommerce Campaign revenue tracks inbox placement, so the calendar sends get tested before they go out. Newsletters When the inbox is the product, placement is the number that pays, so it gets checked on a schedule. Developers One bearer token, ids you poll and results in JSON: the integration is an afternoon, not a sprint. Enterprise One token per integration, each revocable on its own, so a security review can cut one system's access without touching the rest.

How access works.

One token per integration, a small set of status codes, and the same jobs available to AI clients over MCP.

Tokens you can revoke one at a time

Every request carries a bearer token in the Authorization header. Tokens are created in your account, one per integration, and revoking one leaves the others working.

A missing, malformed or revoked token answers 401. A valid token on an account that may not make the call answers 403, and the body names the reason, so a billing problem is never mistaken for a broken integration.

Ids you poll, not webhooks you host

A call that starts work answers with an id. You poll that id until the result is ready, which keeps the integration to plain outbound HTTP with nothing of yours exposed publicly.

The API uses a small set of codes and nothing outside it. A 422 means the request parsed and the values were rejected, with the fields named, so a bad payload never looks like a rejected account.

The same jobs over MCP

AI clients reach the same work over MCP, as JSON-RPC 2.0 to a single endpoint, so an assistant can run a spam check and read the result without anyone writing a client for it.

MCP authenticates with OAuth 2.1 and there is no token to paste: the client runs the flow when you add the server. The bearer token above is for the REST API only.

From token to result in four steps.

The spam check is the shortest path through the API. Inbox placement and previews follow the same shape: start something, take the id, read the result.

01
Create a token

In your account, one token per integration, each revocable on its own.
02
Start a test

POST to the spam check endpoint. The response carries the test id and the address to send your email to.
03
Send the email

From the platform you really send with, to the address the API returned, so the test measures your actual sending setup rather than a copy of it.
04
Read the result

GET the test by its id for the score and the authentication results, then ask for the heatmap or the client previews on the same id.

Frequently asked questions about the API.

Plans, limits, where the reference lives, and what a 403 is telling you.

Which plan includes API access?

API access is included with the White Label plan. The current prices are on the pricing page.

Is there a reference with every parameter?

Yes. The OpenAPI document is the reference, and it is generated from the API itself, so it cannot describe a call the service does not answer. It is linked from the code sample above.

What are the rate limits?

The REST API publishes no rate limit and no endpoint documents a 429 response. Read that as unspecified rather than unlimited, and back off on repeated failures instead of assuming a budget. The MCP server does limit requests per account and answers 429 once you pass the limit.

What does a 403 mean?

The token is valid and the account may not make that call. The body carries a reason: the account email is not confirmed yet, the plan allowance for that call is spent for the period, or the plan does not include API access.

Can an AI assistant use it?

Yes, over MCP rather than REST. The MCP server exposes the same jobs as tools an assistant can call, with OAuth 2.1 in place of a bearer token.

Does it need access to my email platform?

Not for a spam check or a preview. You send a message to an address the API gives you, from whatever you already send with, and the API reads what arrived. Recurring automatic tests are different, because something has to send them on a schedule, so a sender is connected over SMTP for those.

Ready to wire deliverability into your own stack?