# Placement tests

> Send an email to test inboxes at each provider and see where it lands. 4 Ballast REST endpoints with parameters, permissions, the MCP tool and a curl example.

Canonical: https://ballast.to/docs/api/placement-tests

[API reference](https://ballast.to/docs/api)

Send an email to test inboxes at each provider and see where it lands. 4 endpoints, each also a tool for your AI through [MCP](https://ballast.to/docs/mcp). Authentication and errors are on the [overview](https://ballast.to/docs/api#authentication).

## List inbox placement tests

GET

/api/v1/placement-tests

Newest first, with each test's inbox rate by provider. Also says which test inboxes are available and how many tests are left today (up to 10 a day).

MCP tool

list\_placement\_tests

Read-only

Parameters

- **`campaignId` query · string**: Only tests of this campaign's emails
- **`limit` query · integer**

Returns

- **`tests` required object\[\]**
- **`seeds` required object\[\]**: Test inboxes available now, by provider
- **`testsLeft` required number**
- **`limits` required object**

cURL

```
curl https://ballast.to/api/v1/placement-tests \
  -H "Authorization: Bearer $BALLAST_API_KEY"
```

## Get an inbox placement test

GET

/api/v1/placement-tests/{id}

Where each email landed (inbox, spam or missing, and the Gmail or Outlook tab), the inbox rate overall, by provider and by mailbox, and the email that was sent. Results arrive over about an hour; status is running until then.

MCP tool

get\_placement\_test

Read-only

Parameters

- **`id` required path · string**

Returns

- **`id` required string**
- **`name` required string**: The campaign's name, or the subject of an email written for the test
- **`detail` required string | null**: Which email: "Step 1, variant B", or "Your own email"; null when the campaign email no longer exists
- **`source` required "campaign" | "custom"**
- **`campaignId` required string | null**
- **`stepId` required string | null**
- **`variantId` required string | null**
- **`status` required "running" | "done"**: running until every email was found or the last look passed (about an hour after sending)
- **`createdAt` required string**
- **`finishedAt` required string | null**
- **`summary` required object**
- **`email` required object**: The email as the first mailbox sent it
- **`results` required object\[\]**

cURL

```
curl https://ballast.to/api/v1/placement-tests/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY"
```

## Preview an inbox placement test

POST

/api/v1/placement-tests/preview

What run\_placement\_test would send, without sending: the email as rendered, how many emails go to which providers, any mailbox that can't take part and why.

MCP tool

preview\_placement\_test

Parameters

- **`mailboxIds` required string\[\]**: Mailboxes to send from, up to 10. Each sends one email to every test inbox.
- **`variantId` string**: Test a campaign email: the variant's id (get\_campaign lists them). Variables are filled from the campaign's first lead.
- **`subject` string**: Or test your own email: subject line (with variables and spintax if you like)
- **`body` string**: Body for your own email: HTML or plain text

Returns

- **`name` required string**
- **`detail` required string**
- **`emails` required number**: Emails the test sends: one per ready mailbox and test inbox
- **`seeds` required object\[\]**
- **`mailboxes` required object\[\]**
- **`sample` required object**
- **`warnings` required string\[\]**
- **`testsLeft` required number**
- **`blocked` required string | null**: Why the test can't run; null when it can

cURL

```
curl -X POST https://ballast.to/api/v1/placement-tests/preview \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailboxIds":[]}'
```

## Run an inbox placement test

POST

/api/v1/placement-tests

Sends one email from each mailbox (up to 10) to each of Ballast's test inboxes at Gmail, Outlook and other providers, over a few minutes and inside each mailbox's daily limit. Test emails never show in the Unibox or the stats. Read the results with get\_placement\_test.

MCP tool

run\_placement\_test

Needs an active plan

MCP asks to confirm

Parameters

- **`mailboxIds` required string\[\]**: Mailboxes to send from, up to 10. Each sends one email to every test inbox.
- **`variantId` string**: Test a campaign email: the variant's id (get\_campaign lists them). Variables are filled from the campaign's first lead.
- **`subject` string**: Or test your own email: subject line (with variables and spintax if you like)
- **`body` string**: Body for your own email: HTML or plain text

Returns the same fields as Get an inbox placement test.

cURL

```
curl -X POST https://ballast.to/api/v1/placement-tests \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailboxIds":[]}'
```