Runs examples for real against your account. Test keys only; kept in this tab, never stored on our side. Get a key
ZapSMTP / Docs / Inbox placement

Start a placement test

POST/v1/placement-tests

Start an inbox placement test: see whether a message lands in the inbox, a Gmail tab or spam at the big mailbox providers.

Requires a full-access live key; test keys get 403 test_key_restricted.

With a message (from and content, or a template) one copy goes to each seed mailbox through your account, like any send (each counts as a sent email; test keys cannot). Without one the test is manual: send your message to every address in results from anywhere, with token in the subject or text, within 2 hours.

ZapSMTP then reads each seed mailbox (Gmail, Outlook, Yahoo and others) and records where the copy landed: inbox, a Gmail tab (promotions, social, updates, forums), spam, or missing once the test ends (15 minutes after a send). auth is the provider's own SPF, DKIM and DMARC verdict.

status is running until every seed has an answer or the test ends, then done. summary.inbox_rate = inbox (any tab) / seeds with an answer.

Your plan includes a number of tests a month (Free 1, Pro 10, Scale 50); over it: 429 monthly_quota_exceeded.

Body parameters

fromstring
Sender on one of your verified domains. Leave out (with template) for a manual test.
subjectstring
As in Send an email.
htmlstring
As in Send an email.
textstring
As in Send an email.
templateobject
A stored template and its variables, as in Send an email.
headersobject
Extra headers, as in Send an email.
tagsobject[]
As in Send an email.
streamstring
As in Send an email.

Errors

test_key_restrictedHTTP 403
test-mode keys can send test email and read, not change the account: use a live key
monthly_quota_exceededHTTP 429
this month's inbox placement tests of the plan are used up
service_unavailableHTTP 503
no seed mailboxes are configured
POST/v1/placement-tests
curl -X POST 'https://api.zapsmtp.com/v1/placement-tests' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "News <news@example.com>",
  "subject": "November offers",
  "html": "<p>Our November offers</p>"
}'
Set ZAP_API_KEY in your environment.
Response 201 Created
{
  "object": "placement_test",
  "id": "019a2b10-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "mode": "send",
  "token": "zp-4f9k2m8q1x7c3v5b",
  "from": "News <news@example.com>",
  "subject": "November offers",
  "status": "running",
  "created_at": "2026-11-02T10:00:00Z",
  "ends_at": "2026-11-02T10:15:00Z",
  "finished_at": null,
  "results": [
    {
      "provider": "gmail",
      "address": "seed1@gmail.com",
      "email_id": "019a2b10-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
      "placement": null,
      "folder": null,
      "received_at": null,
      "auth": null
    },
    {
      "provider": "outlook",
      "address": "seed1@outlook.com",
      "email_id": "019a2b10-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
      "placement": null,
      "folder": null,
      "received_at": null,
      "auth": null
    },
    {
      "provider": "yahoo",
      "address": "seed1@yahoo.com",
      "email_id": "019a2b10-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
      "placement": null,
      "folder": null,
      "received_at": null,
      "auth": null
    }
  ],
  "summary": {
    "total": 3,
    "inbox": 0,
    "primary": 0,
    "promotions": 0,
    "social": 0,
    "updates": 0,
    "forums": 0,
    "spam": 0,
    "missing": 0,
    "pending": 3,
    "inbox_rate": 0
  }
}