v1

latestOpenAPI 3.1.02026-07-2617125852.3 KB

InboxPlacementTest

Create inbox placement test

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

post/api/v2/inbox-placement-tests

Request body

namestring required

Name of the inbox placement test

delivery_mode1 | 2 | null nullable

Whether to send emails one by one or all together

descriptionstring nullable

Description of the inbox placement test

type1 | 2 required

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

sending_method1 | 2 required

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

campaign_idstring uuid nullable

Campaign ID

email_subjectstring required

Email subject of the inbox placement test

email_bodystring required

Email body of the inbox placement test

emailsstring[] required

Emails to send the inbox placement test to

test_codestring nullable

Code for identifying inbox placement tests sent from outside Instantly. Use ptid_ followed by letters, numbers, hyphens, or underscores. When creating a test, the ptid_ prefix is added automatically if omitted. The full code must be at most 50 characters.

tagsstring[] nullable

List of tag IDs to use for sending emails

text_onlyboolean nullable

Disables open tracking

timestamp_next_runstring nullable

Timestamp when the inbox placement test will run next

status1 | 2 | 3 nullable

Status of the inbox placement test

not_sending_status'daily_limits_hit' | 'other' nullable

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

run_immediatelyboolean

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

Example request

{
  "name": "My Inbox Placement Test",
  "delivery_mode": 1,
  "description": "This is a test description",
  "schedule": {
    "days": {
      "0": false,
      "1": false,
      "2": true,
      "3": true,
      "4": false,
      "5": false,
      "6": false
    },
    "timing": {
      "from": "02:30"
    },
    "timezone": "Etc/GMT+12"
  },
  "type": 1,
  "sending_method": 1,
  "campaign_id": "019f94cd-83af-7ac5-acf5-0f68a4abdeac",
  "email_subject": "My Email Subject",
  "email_body": "Hi, this is my email body",
  "emails": [
    "john@doe.com"
  ],
  "test_code": "ptid_abc_DEF-123",
  "tags": [
    "019f94cd-83af-7ac5-acf5-0f692bce3808"
  ],
  "text_only": true,
  "recipients_labels": [
    {
      "region": "North America",
      "sub_region": "US",
      "type": "Professional",
      "esp": "Google"
    }
  ],
  "timestamp_next_run": "2026-07-24T15:45:24.399Z",
  "automations": [
    {
      "when": {
        "condition": "placement_goes_below",
        "condition_value": 80
      },
      "then": {
        "webhook_url": "https://example.com/webhook",
        "pause_sending_campaigns_for": 14,
        "pause": true,
        "enable_slow_ramp": true,
        "disable_slow_ramp": true,
        "add_tags": [
          "019f94cd-83af-7ac5-acf5-0f6b51f6e50e"
        ],
        "remove_tags": [
          "019f94cd-83af-7ac5-acf5-0f6c269291d5"
        ]
      }
    }
  ],
  "status": 1,
  "not_sending_status": "daily_limits_hit",
  "run_immediately": true
}

Response

The Inbox Placement Test

idstring uuid required

Unique identifier for the inbox placement test

organization_idstring uuid required

Organization ID