Inbox Placement API.

Create a test over REST, send your email to each returned mailbox with the test id inside, and read back the folder and tab each one put it in as JSON.

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, then pass them in the next request
curl -X POST https://api.unspam.email/ext/v2/inbox-placement \
  -H "Authorization: Bearer $UNSPAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mailboxes": [3, 7] }'

# returns the test id and the seed mailboxes to send to
{
  "id": "7Hq2xLpV0aKd",
  "mailboxes": [
    { "id": 3, "name": "Gmail", "address": "..." },
    { "id": 7, "name": "Outlook", "address": "..." }
  ]
}

# send to each address with the test id in the subject or body, then read the result
curl https://api.unspam.email/ext/v2/inbox-placement/7Hq2xLpV0aKd \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
{
  "status": "success",
  "results": [
    {
      "mailbox": { "id": 3, "name": "Gmail", ... },
      "status": "success",
      "tab": "Promotions",
      "sender": "news@yourdomain.com",
      "sender_ip": "192.0.2.1",
      "blacklists": 0
    }
  ],
  "report_url": "https://unspam.email/inbox-test/7Hq2xLpV0aKd"
}
Endpoints
20
Results
Per mailbox
Authentication
Bearer token
Rate limit
100 a minute

Why teams pick Unspam for placement monitoring.

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.

Inbox, tab or spam, mailbox by mailbox.

The results[] array carries one entry per mailbox with its delivery status, the tab the email landed in, the sender and sender_ip the receiver saw, and a public-blocklist count in blacklists.

Schedule, poll, alert.

The /scheduled-tests endpoints run placement tests on a schedule you set, with alert settings and results per run. Hook the JSON into Datadog, PagerDuty, Slack, or whatever already pages your team. See automatic testing.

Trend placement over time.

GET /inbox-placement?page=N&per_page=15 returns the tests you created through the API, with id, status, timestamps and the hosted report_url. Read any of them back by id to follow per-mailbox drift week over week without rebuilding storage on your side.

What every inbox-placement test returns.

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

A per-mailbox folder verdict, not a score.

Each results[].tab reports where the email landed in that mailbox: Inbox, Spam, or a Gmail tab such as Promotions, Social, Updates or Forums. It stays null until the message arrives. Aggregate scores hide where reputation damage is actually happening; this answers the question directly.

The status field reports delivery: success once the mailbox has the message, pending while we wait for it, and failed if it never arrived.

  • Gmail Promotions
  • Outlook Inbox
  • Yahoo Mail Spam
  • Zoho Inbox
  • AOL null

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.

  • status success
  • tab Inbox
  • sender send@yourdomain.com
  • sender_ip 192.0.2.1
  • blacklists 0

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.

  • Gmail id: 3
  • Outlook id: 7
  • AOL id: 23

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 in the subject or body so our engine can match the message to the test.

  4. 04

    Read per-mailbox verdicts

    GET /ext/v2/inbox-placement/{id} returns results[] with each mailbox's status, tab, sender_ip and blacklists count. Poll until the test's own status leaves pending: it ends as success or failed.

The endpoints behind it.

20 endpoints, on the same token as the rest of the API. The OpenAPI document has every parameter and response code.

OpenAPI document
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 10 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
  • PUT /scheduled-tests/{id}/email
  • GET /scheduled-tests/{id}/runs
  • GET /scheduled-tests/{id}/runs/{runId}

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 is included with the Custom plan, which you buy online: pick the monthly volume of each test on the pricing page, from a $5 minimum, and the rates drop as you grow. You can build it into your own product and resell it under your own brand. For anything else, open a support ticket.
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 a higher limit, open a support ticket 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 subject or body so we can match it. Then GET /ext/v2/inbox-placement/{id} returns per-mailbox verdicts, and the test's status ends as success or failed.
Which mailboxes are available?
We test against the most popular personal and business email providers. 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 success or failed.
Can I build this into my own product and resell it?
Yes, on the Custom plan. Every placement test comes back as JSON with the folder each mailbox put your email in, so you can show it in your own interface and resell it to your clients under your own brand.
Can I preview the same email in real clients?
Yes. POST /ext/v2/client-previews with email_source set to inbox-placement and the test id as source_id renders the message you sent in real clients and devices. The test result then carries its client_preview_id. See the email preview API.

Bring placement testing into your stack.

API access is included with the Custom plan, bought online from a $5 monthly minimum. Build it into your own product and resell it under your own brand.