// api product · spam tests

Email Spam Checker API.

Create a spam-check via REST, send your email to the inbox address we return, then read back a 0–100 deliverability score with sender forensics, per-check breakdown, screenshots, and AI heatmaps as JSON.

POST /ext/v2/spam-check

// 1. create a spam-check

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

# response (201)
{
  "id": "2Bl8rzTFN6VV",
  "inbox_address": "test-xyz@check.unspam.email"
}

# now send your email to inbox_address
# from your sending platform.

// 2. read the result

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

# response (200)
{
  "id": "2Bl8rzTFN6VV",
  "status": "completed",
  "score": 85,
  "sender": "you@yourdomain.com",
  "sender_ip": "192.0.2.1",
  "results": [
    { "id": "spf_check", ... },
    { "id": "dkim_check", ... },
    { "id": "dmarc_check", ... }
  ],
  "report_url": "https://unspam.email/result/2Bl8rzTFN6VV"
}

// the api surface

Four request types. One API key.

We offer a range of API request types designed to support your email testing and optimization needs. Tell us which features interest you most and we will help you find the best setup for your use case.

Spam Tests

POST /spam-checkScore, sender forensics, per-check breakdown. Built for sender platforms and CRM teams.

Inbox Placement

POST /inbox-placementSend to our seed list, get per-mailbox folder (inbox / promotions / spam) + blacklist exposure.

Email Previews

GET /spam-check/{id}/screenshotsDesktop, tablet, and mobile renders of your email as CDN-hosted PNGs.

Email Heatmaps

GET /spam-check/{id}/heatmapAI-generated focus + attention heatmaps across all three device sizes.

// at a glance

Why teams ship Unspam as their spam-check API.

// async by design

Async create-then-read flow.

POST creates a test and hands back a unique inbox address. Send your real email there from your existing infrastructure, then GET the result. No payload limits, no MIME shimming.

// score + forensics

0–100 score plus sender + auth detail.

Every completed test returns the score, sender host, sender IP, message-ID, and a results[] array with SPF/DKIM/DMARC and content-level checks. One read covers the whole verdict.

// visual extras

Screenshots and AI heatmaps in-line.

Each spam-check carries two sub-resources: /screenshots returns desktop/tablet/mobile renders, /heatmap returns AI-generated focus + attention maps for the same email.

// persistent history

Every test, kept and paginated.

Past spam-checks stay on file. GET /spam-check?page=N&per_page=15 returns the paginated list with id, status, score, timestamps, and the hosted report_url. Embed historical results in your own dashboard without re-running the test.

// deep dive

What every spam-check returns.

A 0–100 deliverability score, the per-check breakdown that drives it, and visual + AI extras for QA pipelines.

// 01

A single 0–100 score for the deliverability hop.

The score field rolls every signal (authentication, content, blocklists, headers) into one number a CI step can branch on. 80+ is healthy, 50–70 is risky, sub-50 is likely landing in spam.

Pair with report_url if your humans need the full visual breakdown; both fields land in the same response.

// spam-check / 2Bl8rzTFN6VV INBOX

85/100

0: spam 100: clean

// 02

A per-check breakdown in the same payload.

The results[] array enumerates every check the engine ran: SPF, DKIM, DMARC, BIMI, spam-word density, link reputation, image-to-text ratio, and more. Each entry has a stable id you can map to your own dashboard.

No separate endpoint to pull check-by-check verdicts. One GET, the whole story.

// results[]

SPF Check spf_check
DKIM Check dkim_check
DMARC Check dmarc_check
Spam words spam_words
Link reputation link_rep
Image / text ratio img_ratio

// 03

Screenshots and AI heatmaps on the same test.

GET /spam-check/{id}/screenshots returns CDN URLs for desktop, tablet, and mobile renders of your email. Drop them into your CI artifacts or your sender dashboard with no further processing.

GET /spam-check/{id}/heatmap returns AI-generated focus and attention heatmaps across the same three devices, so you can see exactly where readers will look before you ship the next send.

// /screenshots + /heatmap

desktop

tablet

mobile

// what we check

How the API works in four steps.

The spam-check API is asynchronous: you create a test, send your email to the inbox address we return, then read the verdict.

01
Create a spam-check

POST /ext/v2/spam-check with your bearer token. The 201 response hands back a test id and a unique inbox_address.
02
Send your email to the inbox address

From your transactional pipeline, marketing platform, or a CI step. The message routes through our spam-check engine, which holds it for analysis.
03
Read the verdict

GET /ext/v2/spam-check/{id} returns the score, sender forensics, message-ID, and the results[] array once status flips to "completed". Poll on a back-off or wire it to a job worker.
04
Pull screenshots and heatmaps (optional)

/spam-check/{id}/screenshots for the three device renders. /spam-check/{id}/heatmap for AI focus + attention maps. Both share the same test id, so there is no extra credit accounting in your code.

// FAQ

Frequently asked questions about the API.

Integration, billing, rate limits, and what the spam-check endpoint returns.

How do I get API access?

API access ships under our White Label plan, which is fully custom: limits for spam-checks, inbox-placement tests, screenshots, and heatmaps are sized to your account. Talk to sales with your expected volume and we will scope a fit.

What are the rate limits?

The public limit is 100 requests per minute per IP or per authenticated account. That covers most production traffic. If you need higher burst capacity or a dedicated lane, open chat with your expected throughput.

How does the create-then-read flow work?

It is two calls. POST /ext/v2/spam-check returns an inbox_address; your sending platform delivers the real email to that address; then GET /ext/v2/spam-check/{id} returns the verdict once status === "completed". Most checks finish in a few seconds, so back off with exponential delay or use a job worker.

Can I check my remaining quota from the API?

GET /ext/v2/status returns your email, subscription name, and the limits map (spam_check, inbox_placement, screenshots, heatmaps, has_history, has_ai_assistant). Useful for showing usage in your own admin UI.

How accurate is the spam score?

The score reflects how our engines and seed accounts rate the message. Real-world delivery still depends on sending reputation, list hygiene, and recipient engagement. The API gives you the content and authentication signal, not a guarantee of inbox placement.

Can I call the API from any language?

Yes. The API is REST + JSON over HTTPS. Any HTTP client works (curl, Node, Python, Go, Ruby, PHP, …). No mandatory SDK; auth is a single Authorization: Bearer YOUR_API_TOKEN header.

Is there a sandbox or free trial?

We do not publish a self-serve API trial. Talk to sales for evaluation access. Most teams pilot via the free web tool first to confirm the test logic matches their use case.

// next step

Ready to wire Unspam into your stack?

API access is included with the White Label plan. Pricing on the public page, custom limits over chat.

See pricing →