Inbox Placement Test

API Explorer (2.0.0)

The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the ApiKeyAuth_token blue text.

Languages
Servers
Instantly API Server

https://api.instantly.ai/

Mock server

https://developer.instantly.ai/_mock/api/v2/

Analytics

Endpoints related to analytics

Operations

Account

An email account that can be used to send campaigns

Operations

Campaign

A campaign that can be sent to a list of recipients

Operations

Email

A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox

Operations

Email Verification

A single email verification

Operations

Lead List

A list used to store leads

Operations

Inbox Placement Test

An inbox placement test

Operations

Inbox Placement Test

An inbox placement test

idstring(uuid)read-onlyrequired

Unique identifier for the inbox placement test

Example: "019769d6-c129-7796-9640-1aff84ca5b00"
organization_idstring(uuid)read-onlyrequired

Organization ID

Example: "019769d6-c129-7796-9640-1b0045d17645"
namestringrequired

Name of the inbox placement test

Example: "My Inbox Placement Test"
typenumberrequired

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
email_subjectstringrequired

Email subject of the inbox placement test

Example: "My Email Subject"
email_bodystringrequired

Email body of the inbox placement test

Example: "Hi, this is my email body"
recipientsArray of stringsread-onlyrequired
Example: ["johndoe@instantly.ai"]
timestamp_createdstringread-onlyrequired

Timestamp when the inbox placement test was created

Example: "2025-06-13T15:09:31.306Z"
delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
descriptionnull or string

Description of the inbox placement test

Example: "This is a test description"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

Example: {"days":{"2":true,"3":true},"timing":{"from":"02:30"},"timezone":"America/Chihuahua"}
sending_methodnull or number

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
emailsArray of strings or null

Emails to send the inbox placement test to

test_codenull or string

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

text_onlynull or boolean

Disables open tracking

Example: true
recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

timestamp_next_runnull or string

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnull or number

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
not_sending_statusnull or string

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
{
  "id": "019769d6-c129-7796-9640-1aff84ca5b00",
  "organization_id": "019769d6-c129-7796-9640-1b0045d17645",
  "name": "My Inbox Placement Test",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": { … },
    "timing": { … },
    "timezone": "America/Chihuahua"
  },
  "type": 1,
  "sending_method": 1,
  "campaign_id": "019769d6-c129-7796-9640-1b01a18395df",
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": null,
  "test_code": "ptid_UQxUfnJKYAgfnS_Vq5F4l",
  "tags": null,
  "text_only": true,
  "recipients": [
    "johndoe@instantly.ai"
  ],
  "recipients_labels": [
    { … }
  ],
  "timestamp_created": "2025-06-13T15:09:31.306Z",
  "timestamp_next_run": "2025-06-13T15:09:31.306Z",
  "automations": null,
  "status": 1,
  "not_sending_status": "daily_limits_hit"
}

Create inbox placement test

Request

Requires one of the following scopes: inbox_placement_tests:create, inbox_placement_tests:all, all:create, all:all

Bodyapplication/jsonrequired

The Inbox Placement Test to create

namestringrequired

Name of the inbox placement test

Example: "My Inbox Placement Test"
typenumberrequired

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
email_subjectstringrequired

Email subject of the inbox placement test

Example: "My Email Subject"
email_bodystringrequired

Email body of the inbox placement test

Example: "Hi, this is my email body"
delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
descriptionstring or null

Description of the inbox placement test

Example: "This is a test description"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

sending_methodnumber or null

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
emailsArray of strings or null

Emails to send the inbox placement test to

Example: ["john@doe.com"]
test_codestring or null

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

Example: ["019769d6-c12a-7c25-9286-fdcd7482d2b6"]
text_onlyboolean or null

Disables open tracking

Example: true
recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

timestamp_next_runstring or null

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnumber or null

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
not_sending_statusstring or null

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
run_immediatelyboolean

Run the test immediately after creation, as well as on the schedule

Example: true
curl -i -X POST \
  https://api.instantly.ai/api/v2/inbox-placement-tests \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Inbox Placement Test",
    "type": 1,
    "email_subject": "My Email Subject",
    "email_body": "Hi, this is my email body"
  }'

Responses

The Inbox Placement Test

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the inbox placement test

Example: "019769d6-c129-7796-9640-1aff84ca5b00"
organization_idstring(uuid)read-onlyrequired

Organization ID

Example: "019769d6-c129-7796-9640-1b0045d17645"
namestringrequired

Name of the inbox placement test

Example: "My Inbox Placement Test"
typenumberrequired

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
email_subjectstringrequired

Email subject of the inbox placement test

Example: "My Email Subject"
email_bodystringrequired

Email body of the inbox placement test

Example: "Hi, this is my email body"
recipientsArray of stringsread-onlyrequired
Example: ["johndoe@instantly.ai"]
timestamp_createdstringread-onlyrequired

Timestamp when the inbox placement test was created

Example: "2025-06-13T15:09:31.306Z"
delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
descriptionnull or string

Description of the inbox placement test

Example: "This is a test description"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

Example: {"days":{"2":true,"3":true},"timing":{"from":"02:30"},"timezone":"America/Chihuahua"}
sending_methodnull or number

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
emailsArray of strings or null

Emails to send the inbox placement test to

test_codenull or string

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

text_onlynull or boolean

Disables open tracking

Example: true
recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

timestamp_next_runnull or string

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnull or number

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
not_sending_statusnull or string

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
Response
application/json
{
  "id": "019769d6-c129-7796-9640-1aff84ca5b00",
  "organization_id": "019769d6-c129-7796-9640-1b0045d17645",
  "name": "My Inbox Placement Test",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": { … },
    "timing": { … },
    "timezone": "America/Chihuahua"
  },
  "type": 1,
  "sending_method": 1,
  "campaign_id": "019769d6-c129-7796-9640-1b01a18395df",
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": null,
  "test_code": "ptid_UQxUfnJKYAgfnS_Vq5F4l",
  "tags": null,
  "text_only": true,
  "recipients": [
    "johndoe@instantly.ai"
  ],
  "recipients_labels": [
    { … }
  ],
  "timestamp_created": "2025-06-13T15:09:31.306Z",
  "timestamp_next_run": "2025-06-13T15:09:31.306Z",
  "automations": null,
  "status": 1,
  "not_sending_status": "daily_limits_hit"
}

List inbox placement test

Request

Requires one of the following scopes: inbox_placement_tests:read, inbox_placement_tests:all, all:read, all:all

Query
limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10
starting_afterstring

The ID of the last item in the previous page - used for pagination. You can use the value of the next_starting_after field from the previous response.

Example: starting_after=01956fbd-0eb1-72db-a565-82977a586084
searchstring
Example: search=test
statusnumber
Enum123
Example: status=1
sort_columnstring
Example: sort_column=id
sort_orderstring
Example: sort_order=desc
curl -i -X GET \
  'https://api.instantly.ai/api/v2/inbox-placement-tests?limit=10&search=test&sort_column=id&sort_order=desc&starting_after=01956fbd-0eb1-72db-a565-82977a586084&status=1' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of Inbox Placement Test

Bodyapplication/json
itemsArray of objects(Inbox Placement Test)required
items[].​idstring(uuid)read-onlyrequired

Unique identifier for the inbox placement test

Example: "019769d6-c129-7796-9640-1aff84ca5b00"
items[].​organization_idstring(uuid)read-onlyrequired

Organization ID

Example: "019769d6-c129-7796-9640-1b0045d17645"
items[].​namestringrequired

Name of the inbox placement test

Example: "My Inbox Placement Test"
items[].​typenumberrequired

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
items[].​email_subjectstringrequired

Email subject of the inbox placement test

Example: "My Email Subject"
items[].​email_bodystringrequired

Email body of the inbox placement test

Example: "Hi, this is my email body"
items[].​recipientsArray of stringsread-onlyrequired
Example: ["johndoe@instantly.ai"]
items[].​timestamp_createdstringread-onlyrequired

Timestamp when the inbox placement test was created

Example: "2025-06-13T15:09:31.306Z"
items[].​delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
items[].​descriptionnull or string

Description of the inbox placement test

Example: "This is a test description"
items[].​scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

Example: {"days":{"2":true,"3":true},"timing":{"from":"02:30"},"timezone":"America/Chihuahua"}
items[].​sending_methodnull or number

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
items[].​campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
items[].​emailsArray of strings or null

Emails to send the inbox placement test to

items[].​test_codenull or string

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
items[].​tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

items[].​text_onlynull or boolean

Disables open tracking

Example: true
items[].​recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

items[].​timestamp_next_runnull or string

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
items[].​automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

items[].​statusnull or number

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
items[].​not_sending_statusnull or string

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a MongoDB ID, a timestamp, on an email depending on the specific API

Example: "019769d6-da63-7632-8d49-e25149e4ae00"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "019769d6-da63-7632-8d49-e25149e4ae00"
}

Get inbox placement test

Request

Requires one of the following scopes: inbox_placement_tests:read, inbox_placement_tests:all, all:read, all:all

Path
idstring(uuid)required

The ID of the requested item

Example: 019769d6-da64-7800-a03b-c6c63dea0945
Query
with_metadataboolean

Whether to include additional metadata about the inbox placement test

Example: with_metadata=true
curl -i -X GET \
  'https://api.instantly.ai/api/v2/inbox-placement-tests/019769d6-da64-7800-a03b-c6c63dea0945?with_metadata=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Inbox Placement Test

Bodyapplication/json
idstring(uuid)read-only

Unique identifier for the inbox placement test

Example: "019769d6-c129-7796-9640-1aff84ca5b00"
organization_idstring(uuid)read-only

Organization ID

Example: "019769d6-c129-7796-9640-1b0045d17645"
namestring

Name of the inbox placement test

Example: "My Inbox Placement Test"
delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
descriptionnull or string

Description of the inbox placement test

Example: "This is a test description"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

typenumber

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
sending_methodnull or number

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
email_subjectstring

Email subject of the inbox placement test

Example: "My Email Subject"
email_bodystring

Email body of the inbox placement test

Example: "Hi, this is my email body"
emailsArray of strings or null

Emails to send the inbox placement test to

Example: ["john@doe.com"]
test_codenull or string

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

Example: ["019769d6-c12a-7c25-9286-fdcd7482d2b6"]
text_onlynull or boolean

Disables open tracking

Example: true
recipientsArray of stringsread-only
Example: ["johndoe@instantly.ai"]
recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

timestamp_createdstringread-only

Timestamp when the inbox placement test was created

Example: "2025-06-13T15:09:31.306Z"
timestamp_next_runnull or string

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnull or number

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
not_sending_statusnull or string

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
metadataobject

Included only when the with_metadata parameter is true. Contains additional information about the inbox placement test as associated campaign details and tags.

Example: {"campaign":{"id":"campaign-id","name":"Campaign Name"},"tags":{"tag-id":{"id":"tag-id","label":"Tag Label"}}}
Response
application/json
{
  "id": "019769d6-c129-7796-9640-1aff84ca5b00",
  "organization_id": "019769d6-c129-7796-9640-1b0045d17645",
  "name": "My Inbox Placement Test",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": { … },
    "timing": { … },
    "timezone": "Etc/GMT+12"
  },
  "type": 1,
  "sending_method": 1,
  "campaign_id": "019769d6-c129-7796-9640-1b01a18395df",
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": null,
  "test_code": "ptid_UQxUfnJKYAgfnS_Vq5F4l",
  "tags": null,
  "text_only": true,
  "recipients": [
    "johndoe@instantly.ai"
  ],
  "recipients_labels": [
    { … }
  ],
  "timestamp_created": "2025-06-13T15:09:31.306Z",
  "timestamp_next_run": "2025-06-13T15:09:31.306Z",
  "automations": null,
  "status": 1,
  "not_sending_status": "daily_limits_hit",
  "metadata": {
    "campaign": { … },
    "tags": { … }
  }
}

Delete inbox placement test

Request

Requires one of the following scopes: inbox_placement_tests:delete, inbox_placement_tests:all, all:delete, all:all

Path
idstring(uuid)required

The ID of the item to delete

Example: 019769d6-da65-796a-858b-4eb8df1e9144
Bodyapplication/json
null
curl -i -X DELETE \
  https://api.instantly.ai/api/v2/inbox-placement-tests/019769d6-da65-796a-858b-4eb8df1e9144 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

The deleted Inbox Placement Test

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the inbox placement test

Example: "019769d6-c129-7796-9640-1aff84ca5b00"
organization_idstring(uuid)read-onlyrequired

Organization ID

Example: "019769d6-c129-7796-9640-1b0045d17645"
namestringrequired

Name of the inbox placement test

Example: "My Inbox Placement Test"
typenumberrequired

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
email_subjectstringrequired

Email subject of the inbox placement test

Example: "My Email Subject"
email_bodystringrequired

Email body of the inbox placement test

Example: "Hi, this is my email body"
recipientsArray of stringsread-onlyrequired
Example: ["johndoe@instantly.ai"]
timestamp_createdstringread-onlyrequired

Timestamp when the inbox placement test was created

Example: "2025-06-13T15:09:31.306Z"
delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
descriptionnull or string

Description of the inbox placement test

Example: "This is a test description"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

Example: {"days":{"2":true,"3":true},"timing":{"from":"02:30"},"timezone":"America/Chihuahua"}
sending_methodnull or number

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
emailsArray of strings or null

Emails to send the inbox placement test to

test_codenull or string

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

text_onlynull or boolean

Disables open tracking

Example: true
recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

timestamp_next_runnull or string

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnull or number

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
not_sending_statusnull or string

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
Response
application/json
{
  "id": "019769d6-c129-7796-9640-1aff84ca5b00",
  "organization_id": "019769d6-c129-7796-9640-1b0045d17645",
  "name": "My Inbox Placement Test",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": { … },
    "timing": { … },
    "timezone": "America/Chihuahua"
  },
  "type": 1,
  "sending_method": 1,
  "campaign_id": "019769d6-c129-7796-9640-1b01a18395df",
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": null,
  "test_code": "ptid_UQxUfnJKYAgfnS_Vq5F4l",
  "tags": null,
  "text_only": true,
  "recipients": [
    "johndoe@instantly.ai"
  ],
  "recipients_labels": [
    { … }
  ],
  "timestamp_created": "2025-06-13T15:09:31.306Z",
  "timestamp_next_run": "2025-06-13T15:09:31.306Z",
  "automations": null,
  "status": 1,
  "not_sending_status": "daily_limits_hit"
}

Patch inbox placement test

Request

Requires one of the following scopes: inbox_placement_tests:update, inbox_placement_tests:all, all:update, all:all

Path
idstring(uuid)required

The ID of the item to update

Example: 019769d6-da66-74e4-b62c-b1e67650b938
Bodyapplication/json
non-empty
namestring

Name of the inbox placement test

Example: "My Inbox Placement Test"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnumber or null

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
curl -i -X PATCH \
  https://api.instantly.ai/api/v2/inbox-placement-tests/019769d6-da66-74e4-b62c-b1e67650b938 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The updated Inbox Placement Test

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the inbox placement test

Example: "019769d6-c129-7796-9640-1aff84ca5b00"
organization_idstring(uuid)read-onlyrequired

Organization ID

Example: "019769d6-c129-7796-9640-1b0045d17645"
namestringrequired

Name of the inbox placement test

Example: "My Inbox Placement Test"
typenumberrequired

Whether the inbox placement test is a one-time test or an automated test

Enum12
Example: 1
email_subjectstringrequired

Email subject of the inbox placement test

Example: "My Email Subject"
email_bodystringrequired

Email body of the inbox placement test

Example: "Hi, this is my email body"
recipientsArray of stringsread-onlyrequired
Example: ["johndoe@instantly.ai"]
timestamp_createdstringread-onlyrequired

Timestamp when the inbox placement test was created

Example: "2025-06-13T15:09:31.306Z"
delivery_modenull or number

Whether to send emails one by one or all together

Enum ValueDescription
1

One by one

2

All together

Example: 1
descriptionnull or string

Description of the inbox placement test

Example: "This is a test description"
scheduleobject

Specifies the date and time when the automated inbox placement tests will be sent.

Example: {"days":{"2":true,"3":true},"timing":{"from":"02:30"},"timezone":"America/Chihuahua"}
sending_methodnull or number

Whether the inbox placement test will be sent from Instantly or from outside Instantly

Enum ValueDescription
1

From Instantly

2

From Outside Instantly

Example: 1
campaign_idnull or string(uuid)

Campaign ID

Example: "019769d6-c129-7796-9640-1b01a18395df"
emailsArray of strings or null

Emails to send the inbox placement test to

test_codenull or string

Code for identifying the inbox placement tests in the email body from outside Instantly

Example: "ptid_UQxUfnJKYAgfnS_Vq5F4l"
tagsArray of strings or null(uuid)

List of tag IDs to use for sending emails

text_onlynull or boolean

Disables open tracking

Example: true
recipients_labelsArray of objects

A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the GET: /inbox-placement-tests/email-service-provider-options endpoint

timestamp_next_runnull or string

Timestamp when the inbox placement test will run next

Example: "2025-06-13T15:09:31.306Z"
automationsArray of objects or null>= 0 items

Optional automations to trigger based on conditions

statusnull or number

Status of the inbox placement test

Enum ValueDescription
1

Active

2

Paused

3

Completed

Example: 1
not_sending_statusnull or string

Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.

Enum ValueDescription
daily_limits_hit

Daily limits hit

other

Other reason

Example: "daily_limits_hit"
Response
application/json
{
  "id": "019769d6-c129-7796-9640-1aff84ca5b00",
  "organization_id": "019769d6-c129-7796-9640-1b0045d17645",
  "name": "My Inbox Placement Test",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": { … },
    "timing": { … },
    "timezone": "America/Chihuahua"
  },
  "type": 1,
  "sending_method": 1,
  "campaign_id": "019769d6-c129-7796-9640-1b01a18395df",
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": null,
  "test_code": "ptid_UQxUfnJKYAgfnS_Vq5F4l",
  "tags": null,
  "text_only": true,
  "recipients": [
    "johndoe@instantly.ai"
  ],
  "recipients_labels": [
    { … }
  ],
  "timestamp_created": "2025-06-13T15:09:31.306Z",
  "timestamp_next_run": "2025-06-13T15:09:31.306Z",
  "automations": null,
  "status": 1,
  "not_sending_status": "daily_limits_hit"
}

Get ESP options

Request

Provides a list of available email service providers for inbox placement tests.

curl -i -X GET \
  https://api.instantly.ai/api/v2/inbox-placement-tests/email-service-provider-options \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/jsonArray [
regionstringrequired
Example: "North America"
sub_regionstringrequired
Example: "US"
typestringrequired
Example: "Professional"
espstringrequired
Example: "Google"
]
Response
application/json
[
  {
    "region": "North America",
    "sub_region": "US",
    "type": "Professional",
    "esp": "Google"
  }
]

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

Operations

Inbox Placement Blacklist & SpamAssassin Report

Report data for an inbox placement test

Operations

API Key

API Key

Operations

Account Campaign Mapping

Account Campaign Mapping

Operations

Lead

A lead entity representing an individual lead

Operations

Background Job

A background job that can be used to perform long-running tasks

Operations

Custom Tag

A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.

Operations

Block List Entry

A blocked email or domain

Operations

Lead Label

A custom label for categorizing and managing leads

Operations

Workspace

A workspace entity representing a workspace

Operations

Workspace Group Member

A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.

Operations

Workspace Member

A member of a workspace with associated user details

Operations

Campaign Subsequence

A subsequence entity representing a follow-up sequence

Operations

Audit Log

Audit log records for tracking system activities

Operations

Schemas