Inbox Placement Tester API

The Inbox Placement Tester API lets you create, monitor, and manage inbox placement tests from your application. A test provides seed email addresses across mailbox providers so you can send a campaign and see whether it lands in the inbox or spam folder.

Use the API to automate test creation, retrieve placement results, and receive a webhook when a test is complete.

Base path

All endpoints below use the following base path:

Authentication

Authenticate every request with your ZeroBounce API key:

You may also send the key as either api_key or apiKey in the query string.

Typical workflow

Optionally retrieve available providers with GET /api/ipt/providers.
Create a test with POST /api/ipt/test.
Send the campaign according to the test type and the returned seed addresses.
Poll GET /api/ipt/test/{id}, or configure a webhook and wait for the completed result.

Inbox Placement Tester API calls use the same inbox-test credits as the ZeroBounce dashboard. Creating a test fails when your account has no available tests.

Test types

Test type
Value
Additional create field
How to send your campaign

Auto Alias
3
None
Send to the returned emailAddressList. The list includes testid+{identifier}@zbtest.org.
Unique ID
2
None
Include the returned identifier in the campaign subject or body, then send to the seed addresses.
Email
1
senderEmail required
Send the campaign from that address. Matching uses the From header.

3 (Auto Alias) is the default test type.

Create a test

POST /api/ipt/test

Create an inbox placement testⓘ and receive the seed addresses you need to use for your campaign.

Request body

Parameter
Type
Required
Description

name
string, max 64 characters
Yes
A unique name for the test. Allowed characters: letters, numbers, - / \\ , . & ' ( ). The name must be unique among running and finished tests.
testType
1, 2, or 3
No
Test matching method. Defaults to 3 (Auto Alias).
senderEmail
email
Conditional
Required when testType is 1.
providerIds
integer array
No
Use all active seeds for the selected providers.
seedIds
integer array
No
Use specific seed mailboxes.
providers
object array
No
Limit the number of seeds per provider. Each object contains id and maxSeeds; maxSeeds must be at least 1.
webhookUrl
URL
No
Sets the webhook URL for this test and saves it on the API key.

If you do not provide providerIds, seedIds, or providers, the test uses all active seeds. Each test must include at least one non-gateway seed; Mimecast and Proofpoint gateway seeds alone are not sufficient.

Request examples

Create a default Auto Alias test:

Create a test that uses Gmail seeds only:

Create an Email test matched by the From address:

Successful response

The API returns 201 Created.

Send your campaign using the method for the returned test type. For Auto Alias tests, send to every address in emailAddressList.

Providers

GET /api/ipt/providers

Retrieve the seed providers available for new tests. Use the IDs from emailProviders.items and gatewayProviders.items in providerIds or providers when creating a test.

Each provider item includes:

Field
Description

id
Provider identifier used in create requests
name
Provider name
location
Provider location
seedCount
Number of available seeds
seedIds
Available seed mailbox identifiers

Test type reference

GET /api/ipt/test-types

Retrieve the supported test types and the default test type. The default is 3 (Auto Alias).

Get one test

GET /api/ipt/test/{id}

Retrieve the current status and placement results for a test. This endpoint does not accept a request body.

The response includes the test status, counts, percentages, results, and per-seed details in seeds.

Field
Description

status
running or finished
inboxCount
Number of seed messages placed in the inbox
spamCount
Number of seed messages placed in spam
pendingCount
Number of seeds still awaiting a result
percentages
Placement percentages
results
Aggregate placement results
seeds
Placement details for each seed mailbox

Use this endpoint to poll a running test until status is finished.

List tests

GET /api/ipt/tests

List Inbox Placement Tester tests for the authenticated API key.

Query parameter
Required
Description

status
No
Filter by running or finished.
createdAfter
No
Return tests created after this ISO datetime.
createdBefore
No
Return tests created before this ISO datetime.
page
No
Page number. Defaults to 1.
page_size
No
Results per page. Defaults to 25; maximum 100.

Delete a test

DELETE /api/ipt/test/{id}

Delete a completed test. Only finished tests can be deleted; attempting to delete a running test returns 400 Bad Request.

Successful response

Webhooks

When a test created via the public IPT API finishes, we POST the results to a URL you set. One URL per API key. Sent once (retries on network/HTTP errors).

How to set it

Default for the key:

PUT /api/ipt/webhook

GET /api/ipt/webhook returns the current URL (or "").

On create:

Optional webhookUrl on POST /api/ipt/test. Used for that test and saved as the key's default.
If you omit it on create, the stored default is used. No URL → no webhook.

What we send

POST JSON, same body as GET /api/ipt/test/{id}:

id, testName, testType, identifier, status (finished)
counts: inboxCount, spamCount, otherCount, notDeliveredCount, pendingCount, percentages
results and per-seed seeds

Your endpoint should accept application/json and return 2xx.

Errors

HTTP status
Meaning

400 Bad Request
Invalid parameters, duplicate test name, attempted deletion of a running test, or no valid seeds.
401 Unauthorized
Missing or invalid API key.
403 Forbidden
No inbox-test credits are available.
404 Not Found
The test does not exist or does not belong to the authenticated API key.

cURL example

Replace YOUR_API_HOST with the applicable ZeroBounce API host and YOUR_API_KEY with an API key from your ZeroBounce account.