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.

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 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

Operations

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

Lead List

A list used to store leads

idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "019769d6-c12d-7c13-979f-e8433551faba"

organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "019769d6-c12d-7c13-979f-e844a8c9466e"

namestringrequired

Name of the lead list

Example: "My Lead List"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-13T15:09:31.309Z"

has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "019769d6-c12d-7c13-979f-e8455fe9f0b7"

{
  "id": "019769d6-c12d-7c13-979f-e8433551faba",
  "organization_id": "019769d6-c12d-7c13-979f-e844a8c9466e",
  "has_enrichment_task": false,
  "owned_by": "019769d6-c12d-7c13-979f-e8455fe9f0b7",
  "name": "My Lead List",
  "timestamp_created": "2025-06-13T15:09:31.309Z"
}

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 Value	Description
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 Value	Description
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 Value	Description
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 Value	Description
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"
}

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

idstring(uuid)read-onlyrequired

Unique identifier for the inbox placement analytics entry

Example: "019769d6-c121-7554-9168-6e4a6c0fe5f4"

timestamp_createdstringread-onlyrequired

Timestamp when the inbox placement analytics was created

Example: "2025-06-13T15:09:31.297Z"

timestamp_created_datestringread-onlyrequired

Date when the inbox placement analytics was created

Example: "2025-06-13"

organization_idstring(uuid)read-onlyrequired

Organization ID

Example: "019769d6-c121-7554-9168-6e4bea377055"

test_idstring(uuid)required

Inbox Placement Test ID

Example: "019769d6-c121-7554-9168-6e4cc13bc68c"

is_spamnull or number

Indicates if the email landed in spam (1 for spam, 0 otherwise)

Example: 1

has_categorynull or number

Indicates if the email was categorized like promotions, social, etc.

Example: 1

sender_emailnull or string

Email address of the sender

Example: "sender@example.com"

sender_espnull or number

The sender ESP (Email Service Provider)

Enum Value	Description
1	Google
2	Microsoft
12	Web.de
13	Libero.it

Example: 1

recipient_emailnull or string

Email address of the recipient

Example: "recipient@example.com"

recipient_espnull or number

The recipient ESP (Email Service Provider)

Enum Value	Description
1	Google
2	Microsoft
12	Web.de
13	Libero.it

Example: 1

recipient_geonull or number

The geographic location of the recipient

Enum Value	Description
1	United States
2	Italy
3	Germany
4	France

Example: 1

recipient_typenull or number

The type of recipient

Enum Value	Description
1	Professional
2	Personal

Example: 1

spf_passnull or number

Indicates if the email passed SPF validation (1 for pass, 0 otherwise)

Example: 1

dkim_passnull or number

Indicates if the email passed DKIM validation (1 for pass, 0 otherwise)

Example: 1

dmarc_passnull or number

Indicates if the email passed DMARC validation (1 for pass, 0 otherwise)

Example: 1

smtp_ip_blacklist_reportnull or object

Blacklist report for the SMTP IP address

authentication_failure_resultsnull or object

Details of authentication failures for SPF, DKIM, and DMARC

{
  "id": "019769d6-c121-7554-9168-6e4a6c0fe5f4",
  "timestamp_created": "2025-06-13T15:09:31.297Z",
  "timestamp_created_date": "2025-06-13",
  "organization_id": "019769d6-c121-7554-9168-6e4bea377055",
  "test_id": "019769d6-c121-7554-9168-6e4cc13bc68c",
  "is_spam": 1,
  "has_category": 1,
  "sender_email": "sender@example.com",
  "sender_esp": 1,
  "recipient_email": "recipient@example.com",
  "recipient_esp": 1,
  "recipient_geo": 1,
  "recipient_type": 1,
  "spf_pass": 1,
  "dkim_pass": 1,
  "dmarc_pass": 1,
  "smtp_ip_blacklist_report": null,
  "authentication_failure_results": null
}