Inbox Placement Tester API

EXTERNAL API USAGE

The ZeroBounce API may not be used externally within a third party product, platform, or service under our standard Terms of Service. External API usage requires prior approval and is subject to additional commercial requirements, including a minimum commitment.

All external use cases must be reviewed to ensure the appropriate agreement is in place and the implementation meets ZeroBounce technical, security, data handling, and branding requirements.

To discuss external API usage or learn more about our Reseller Program, please contact Partners@ZeroBounce.Net.

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 url

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

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

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

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:

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.

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.

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:

What we send

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

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

Errors

cURL example

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