Skip to main content
POST
/
api
/
v2
/
inbox-placement-tests
Create inbox placement test
curl --request POST \
  --url https://api.instantly.ai/api/v2/inbox-placement-tests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "My Inbox Placement Test",
  "type": 1,
  "sending_method": 1,
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": [
    "john@doe.com"
  ]
}
'
{
  "id": "019cc043-af07-7296-9ac4-031e16ac4587",
  "organization_id": "019cc043-af07-7296-9ac4-031f720d9afb",
  "name": "My Inbox Placement Test",
  "type": 1,
  "sending_method": 1,
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": [
    "john@doe.com"
  ],
  "recipients": [
    "johndoe@instantly.ai"
  ],
  "timestamp_created": "2026-03-05T23:09:47.144Z",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": {
      "2": true,
      "3": true
    },
    "timing": {
      "from": "02:30"
    },
    "timezone": "America/Chihuahua"
  },
  "campaign_id": "019cc043-af07-7296-9ac4-0320b4ad9d46",
  "test_code": "ptid_V2JyKxGgdD9XfFyhFeXQR",
  "tags": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "text_only": true,
  "recipients_labels": [
    {
      "region": "North America",
      "sub_region": "US",
      "type": "Professional",
      "esp": "Google"
    }
  ],
  "timestamp_next_run": "2026-03-05T23:09:47.144Z",
  "automations": [
    {
      "when": {
        "condition": "placement_goes_below",
        "condition_value": 123
      },
      "then": {
        "webhook_url": "<string>",
        "pause_sending_campaigns_for": 123,
        "pause": true,
        "enable_slow_ramp": true,
        "disable_slow_ramp": true,
        "add_tags": [
          "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        ],
        "remove_tags": [
          "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        ]
      }
    }
  ],
  "status": 1,
  "not_sending_status": "daily_limits_hit"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The Inbox Placement Test to create

The Inbox Placement Test to create

​
name
string
required

Name of the inbox placement test

Example:

"My Inbox Placement Test"

​
type
enum<number>
required

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

Available options:
1,
2
Example:

1

​
sending_method
enum<number>
required

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

Available options:
1,
2
Example:

1

​
email_subject
string
required

Email subject of the inbox placement test

Example:

"My Email Subject"

​
email_body
string
required

Email body of the inbox placement test

Example:

"Hi, this is my email body"

​
emails
string[]
required

Emails to send the inbox placement test to

​
delivery_mode
null | enum<number>

Whether to send emails one by one or all together

Available options:
1,
2,
null
Example:

1

​
description
string | null

Description of the inbox placement test

Example:

"This is a test description"

​
schedule
object

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

​
campaign_id
null | string<uuid>

Campaign ID

Example:

"019cc043-af07-7296-9ac4-0320b4ad9d46"

​
test_code
string | null

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

Example:

"ptid_V2JyKxGgdD9XfFyhFeXQR"

​
tags
string<uuid>[] | null

List of tag IDs to use for sending emails

​
text_only
boolean | null

Disables open tracking

Example:

true

​
recipients_labels
object[]

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_run
string | null

Timestamp when the inbox placement test will run next

Example:

"2026-03-05T23:09:47.144Z"

​
automations
null | object[]

Optional automations to trigger based on conditions

​
status
enum<number> | null

Status of the inbox placement test

Available options:
1,
2,
3
Example:

1

​
not_sending_status
enum<string> | null

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

Available options:
daily_limits_hit,
other
Example:

"daily_limits_hit"

​
run_immediately
boolean

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

Example:

true

Response

The Inbox Placement Test

An inbox placement test

​
id
string<uuid>
required

Unique identifier for the inbox placement test

Example:

"019cc043-af07-7296-9ac4-031e16ac4587"

​
organization_id
string<uuid>
required

Organization ID

Example:

"019cc043-af07-7296-9ac4-031f720d9afb"

​
name
string
required

Name of the inbox placement test

Example:

"My Inbox Placement Test"

​
type
enum<number>
required

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

Available options:
1,
2
Example:

1

​
sending_method
enum<number>
required

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

Available options:
1,
2
Example:

1

​
email_subject
string
required

Email subject of the inbox placement test

Example:

"My Email Subject"

​
email_body
string
required

Email body of the inbox placement test

Example:

"Hi, this is my email body"

​
emails
string[]
required

Emails to send the inbox placement test to

​
recipients
string[]
required
​
timestamp_created
string
required

Timestamp when the inbox placement test was created

Example:

"2026-03-05T23:09:47.144Z"

​
delivery_mode
null | enum<number>

Whether to send emails one by one or all together

Available options:
1,
2,
null
Example:

1

​
description
null | string

Description of the inbox placement test

Example:

"This is a test description"

​
schedule
object

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"
}
​
campaign_id
null | string<uuid>

Campaign ID

Example:

"019cc043-af07-7296-9ac4-0320b4ad9d46"

​
test_code
null | string

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

Example:

"ptid_V2JyKxGgdD9XfFyhFeXQR"

​
tags
null | string<uuid>[]

List of tag IDs to use for sending emails

​
text_only
null | boolean

Disables open tracking

Example:

true

​
recipients_labels
object[]

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_run
null | string

Timestamp when the inbox placement test will run next

Example:

"2026-03-05T23:09:47.144Z"

​
automations
null | object[]

Optional automations to trigger based on conditions

​
status
null | enum<number>

Status of the inbox placement test

Available options:
1,
2,
3
Example:

1

​
not_sending_status
null | enum<string>

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

Available options:
daily_limits_hit,
other
Example:

"daily_limits_hit"