Login Get Started →
// api product · inbox placement

Inbox Placement API.

List the mailboxes you want to test, create a placement test, send your email to each returned address, then read back per-mailbox folder placement (inbox / promotions / spam) with sender forensics and blocklist exposure as JSON.

GET + POST /ext/v2/inbox-placement
// 1. list available mailboxes 
curl https://api.unspam.email/ext/v2/inbox-placement/mailboxes \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
[
  { "id": 3,  "name": "Gmail",    "address": "..." },
  { "id": 7,  "name": "Outlook",  "address": "..." },
  ...
]

# pick the IDs you want to test,
# pass them in the next request.
// 2. create a placement test 
curl -X POST https://api.unspam.email/ext/v2/inbox-placement \
  -H "Authorization: Bearer $UNSPAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mailboxes": [3] }'

# response (201)
{
  "id": "abc123",
  "mailboxes": [
    { "id": 3, "name": "Gmail", "address": "..." }
  ]
}

# send your email to each address,
# with the test id somewhere in the body.
// 3. read per-mailbox verdicts 
curl https://api.unspam.email/ext/v2/inbox-placement/abc123 \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
{
  "id": "abc123",
  "status": "completed",
  "results": [
    {
      "mailbox": { "name": "Gmail", ... },
      "status":     "delivered",
      "tab":        "inbox",
      "sender_ip":  "192.0.2.1",
      "blacklists": 0
    }
  ],
  "report_url": "https://unspam.email/inbox-placement/abc123"
}
// 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 pick Unspam for placement monitoring.

// scoped tests

Test every mailbox or pick a subset.

Pass {"mailboxes": [3, 7, 23]} to limit a test to specific providers. Leave the body empty to seed across every enabled mailbox. Mailbox IDs come from GET /inbox-placement/mailboxes.

// per-mailbox verdict

Inbox / Promotions / Spam per provider.

The results[] array carries one entry per mailbox with delivery status, the destination tab, sender + sender_ip the receiver saw, and a public-blocklist exposure count.

// monitor continuously

Schedule, poll, alert.

Wire scheduled placement tests into your monitoring stack. Hook the JSON response into Datadog, PagerDuty, Slack, or whatever already pages your team.

// persistent history

Trend placement over time.

Past tests stay on file. GET /inbox-placement?page=N&per_page=15 returns the paginated list with id, status, timestamps, and the hosted report_url. Track per-mailbox drift week-over-week without rebuilding storage on your side.

// deep dive

What every inbox-placement test returns.

A per-mailbox folder verdict, sender forensics, and blocklist exposure: the data your monitoring stack needs to act.

// 01

A per-mailbox folder verdict, not a score.

Each results[].tab field reports where the email landed for that specific provider: "inbox", "promotions", "spam", or "missing". Aggregate scores hide where reputation damage is actually happening. This answers the question directly.

The status field reports delivery: "delivered", "pending", or "missing" if the seed mailbox never received the message at all.

// results[].tab
  • Gmail inbox
  • Outlook promotions
  • Yahoo Mail spam
  • Zoho inbox
  • AOL inbox
// 02

Sender + SMTP forensics in the same payload.

Every result entry carries sender, sender_ip, and blacklists (the count of public blocklists the engine detected on the sending IP at delivery time). You see what the receiver saw, not just what your own logs show.

Pipe these straight into your reputation dashboard or use them to throttle a problematic IP before it impacts the next campaign.

// sender forensics DELIVERED
status
delivered
tab
inbox
sender
send@yourdomain.com
sender_ip
192.0.2.1
blacklists
0
// 03

Filter to the providers your customers use.

GET /ext/v2/inbox-placement/mailboxes returns every enabled mailbox with id, name, and the live address. Pick the IDs that match your audience and pass them to the create endpoint.

No need to seed every provider for a B2B SaaS sending mostly to corporate Outlook. Scope tightly and save your quota.

// /inbox-placement/mailboxes
  • Gmail id: 1
  • Gmail Workspace id: 3
  • Outlook id: 7
  • Yahoo Mail id: 12
  • Zoho id: 18
  • AOL id: 23
// what we check

How the API works in four steps.

Inbox placement is asynchronous: list mailboxes, create a test, send your email to each returned address, then read the per-provider verdicts.

  1. 01

    List available mailboxes

    GET /ext/v2/inbox-placement/mailboxes returns the full set of enabled mailboxes with stable IDs. Useful once at setup, then on a refresh schedule as providers come online.

  2. 02

    Create a placement test

    POST /ext/v2/inbox-placement with an optional mailboxes filter. The 201 response returns the test id and the list of mailbox addresses you need to deliver to.

  3. 03

    Send your email to each address

    Deliver from your platform to every returned address. Include the test id somewhere in the email body so our engine can match the message to the test.

  4. 04

    Read per-mailbox verdicts

    GET /ext/v2/inbox-placement/{id} returns the results[] array with per-mailbox tab, status, sender_ip, and blacklists count once status === "completed".

// FAQ

Frequently asked questions about the API.

Mailbox mechanics, polling, rate limits, and what each provider verdict means.

How do I get API access?

+
API access ships under our White Label plan, which is fully custom: limits for inbox-placement tests, spam-checks, 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-send flow work?

+
Three calls. POST /ext/v2/inbox-placement returns a test id and a list of mailbox addresses. Your platform delivers the real email to each one (with the test id in the body so we can match it). Then GET /ext/v2/inbox-placement/{id} returns per-mailbox verdicts once status === "completed".

Which mailboxes are available?

+
We test against the most popular personal and business email providers. The current pool includes . For the always-current list — including the IDs you can pass to scope a test — call GET /ext/v2/inbox-placement/mailboxes.

Is the placement deterministic?

+
No. Provider filters are sample-based and depend on sending reputation, recipient engagement, and current filter weights. Treat the result as a strong directional signal, not a guarantee that future sends will land in the same folder.

What does the blacklist count tell me?

+
The blacklists field on each result is the number of public blocklists our engine detected the sending IP on at delivery time. Zero is the expected state; anything higher is a reputation problem to chase down through your sender / ESP.

Can I list past tests?

+
Yes. GET /ext/v2/inbox-placement?page=1&per_page=15 returns a paginated list of tests created via the API, with id, status, timestamps, and the report_url for each.

How do I trigger placement tests from a CI pipeline?

+
POST from your build step (curl, Node, Python, or any HTTP client). Read the response, send your email, then poll GET /inbox-placement/{id} with exponential back-off until status is "completed".
// next step

Bring placement testing into your stack.

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

See pricing →