--- title: "Create inbox placement test" method: POST path: "/api/v2/inbox-placement-tests" tags: ["InboxPlacementTest"] --- # Create inbox placement test `POST /api/v2/inbox-placement-tests` Requires one of the following scopes: `inbox_placement_tests:create`, `inbox_placement_tests:all`, `all:create`, `all:all` ## Request body - object — The Inbox Placement Test to create - `name` string, required — Name of the inbox placement test - `delivery_mode` 1 | 2 | null, nullable — Whether to send emails one by one or all together - `description` string, nullable — Description of the inbox placement test - `schedule` object — Specifies the date and time when the automated inbox placement tests will be sent. - `days` object — Days of the week when the test will run, where keys are integers (0-6, 0 = Sunday) and values are booleans indicating active days. - `timing` object — Timing configuration for the scheduled test. - `from` string — The time of day when the test will start (24-hour format). - `timezone` 'Etc/GMT+12' | 'Etc/GMT+11' | 'Etc/GMT+10' | 'America/Anchorage' | 'America/Dawson' | 'America/Creston' | 'America/Chihuahua' | 'America/Boise' | 'America/Belize' | 'America/Chicago' | 'America/Bahia_Banderas' | 'America/Regina' | 'America/Bogota' | 'America/Detroit' | 'America/Indiana/Marengo' | 'America/Caracas' | 'America/Asuncion' | 'America/Glace_Bay' | 'America/Campo_Grande' | 'America/Anguilla' | 'America/Santiago' | 'America/St_Johns' | 'America/Sao_Paulo' | 'America/Argentina/La_Rioja' | 'America/Araguaina' | 'America/Godthab' | 'America/Montevideo' | 'America/Bahia' | 'America/Noronha' | 'America/Scoresbysund' | 'Atlantic/Cape_Verde' | 'Africa/Casablanca' | 'America/Danmarkshavn' | 'Europe/Isle_of_Man' | 'Atlantic/Canary' | 'Africa/Abidjan' | 'Arctic/Longyearbyen' | 'Europe/Belgrade' | 'Africa/Ceuta' | 'Europe/Sarajevo' | 'Africa/Algiers' | 'Africa/Windhoek' | 'Asia/Nicosia' | 'Asia/Beirut' | 'Africa/Cairo' | 'Asia/Damascus' | 'Europe/Bucharest' | 'Africa/Blantyre' | 'Europe/Helsinki' | 'Europe/Istanbul' | 'Asia/Jerusalem' | 'Africa/Tripoli' | 'Asia/Amman' | 'Asia/Baghdad' | 'Europe/Kaliningrad' | 'Asia/Aden' | 'Africa/Addis_Ababa' | 'Europe/Kirov' | 'Europe/Astrakhan' | 'Asia/Tehran' | 'Asia/Dubai' | 'Asia/Baku' | 'Indian/Mahe' | 'Asia/Tbilisi' | 'Asia/Yerevan' | 'Asia/Kabul' | 'Antarctica/Mawson' | 'Asia/Yekaterinburg' | 'Asia/Karachi' | 'Asia/Kolkata' | 'Asia/Colombo' | 'Asia/Kathmandu' | 'Antarctica/Vostok' | 'Asia/Dhaka' | 'Asia/Rangoon' | 'Antarctica/Davis' | 'Asia/Novokuznetsk' | 'Asia/Hong_Kong' | 'Asia/Krasnoyarsk' | 'Asia/Brunei' | 'Australia/Perth' | 'Asia/Taipei' | 'Asia/Choibalsan' | 'Asia/Irkutsk' | 'Asia/Dili' | 'Asia/Pyongyang' | 'Australia/Adelaide' | 'Australia/Darwin' | 'Australia/Brisbane' | 'Australia/Melbourne' | 'Antarctica/DumontDUrville' | 'Australia/Currie' | 'Asia/Chita' | 'Antarctica/Macquarie' | 'Asia/Sakhalin' | 'Pacific/Auckland' | 'Etc/GMT-12' | 'Pacific/Fiji' | 'Asia/Anadyr' | 'Asia/Kamchatka' | 'Etc/GMT-13' | 'Pacific/Apia' — Timezone in which the schedule is set, in IANA timezone format. - `type` 1 | 2, required — Whether the inbox placement test is a one-time test or an automated test - `sending_method` 1 | 2, required — Whether the inbox placement test will be sent from Instantly or from outside Instantly - `campaign_id` string, uuid, nullable — Campaign ID - `email_subject` string, required — Email subject of the inbox placement test - `email_body` string, required — Email body of the inbox placement test - `emails` string[], required — Emails to send the inbox placement test to - `test_code` string, 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. - `tags` string[], nullable — List of tag IDs to use for sending emails - `text_only` boolean, nullable — Disables open tracking - `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 - `region` string, required — The region to send emails to - `sub_region` string, required — The sub-region to send emails to - `type` string, required — The type of email to send - `esp` string, required — The Email Service Provider (ESP) to send emails to - `timestamp_next_run` string, nullable — Timestamp when the inbox placement test will run next - `automations` object[], nullable — Optional automations to trigger based on conditions - `when` object, required - `condition` 'placement_goes_below' | 'placement_goes_above' | 'added_to_blacklists' | 'removed_from_blacklists', required — Condition for automation trigger - `condition_value` number, nullable — Value for condition, if applicable - `then` object, required — Actions to take when condition is met - `webhook_url` string - `pause_sending_campaigns_for` number — Number of days to pause sending campaigns for - `pause` boolean - `enable_slow_ramp` boolean - `disable_slow_ramp` boolean - `add_tags` string[] - `remove_tags` string[] - `status` 1 | 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_immediately` boolean — Run the test immediately after creation, as well as on the schedule ## Response `200` The Inbox Placement Test - InboxPlacementTest — An inbox placement test - `id` string, uuid, required — Unique identifier for the inbox placement test - `organization_id` string, uuid, required — Organization ID - `name` string, required — Name of the inbox placement test - `delivery_mode` 1 | 2 | null, nullable — Whether to send emails one by one or all together - `description` string, nullable — Description of the inbox placement test - `schedule` object — Specifies the date and time when the automated inbox placement tests will be sent. - `days` object — Days of the week when the test will run, where keys are integers (0-6, 0 = Sunday) and values are booleans indicating active days. - `timing` object — Timing configuration for the scheduled test. - `from` string — The time of day when the test will start (24-hour format). - `timezone` 'Etc/GMT+12' | 'Etc/GMT+11' | 'Etc/GMT+10' | 'America/Anchorage' | 'America/Dawson' | 'America/Creston' | 'America/Chihuahua' | 'America/Boise' | 'America/Belize' | 'America/Chicago' | 'America/Bahia_Banderas' | 'America/Regina' | 'America/Bogota' | 'America/Detroit' | 'America/Indiana/Marengo' | 'America/Caracas' | 'America/Asuncion' | 'America/Glace_Bay' | 'America/Campo_Grande' | 'America/Anguilla' | 'America/Santiago' | 'America/St_Johns' | 'America/Sao_Paulo' | 'America/Argentina/La_Rioja' | 'America/Araguaina' | 'America/Godthab' | 'America/Montevideo' | 'America/Bahia' | 'America/Noronha' | 'America/Scoresbysund' | 'Atlantic/Cape_Verde' | 'Africa/Casablanca' | 'America/Danmarkshavn' | 'Europe/Isle_of_Man' | 'Atlantic/Canary' | 'Africa/Abidjan' | 'Arctic/Longyearbyen' | 'Europe/Belgrade' | 'Africa/Ceuta' | 'Europe/Sarajevo' | 'Africa/Algiers' | 'Africa/Windhoek' | 'Asia/Nicosia' | 'Asia/Beirut' | 'Africa/Cairo' | 'Asia/Damascus' | 'Europe/Bucharest' | 'Africa/Blantyre' | 'Europe/Helsinki' | 'Europe/Istanbul' | 'Asia/Jerusalem' | 'Africa/Tripoli' | 'Asia/Amman' | 'Asia/Baghdad' | 'Europe/Kaliningrad' | 'Asia/Aden' | 'Africa/Addis_Ababa' | 'Europe/Kirov' | 'Europe/Astrakhan' | 'Asia/Tehran' | 'Asia/Dubai' | 'Asia/Baku' | 'Indian/Mahe' | 'Asia/Tbilisi' | 'Asia/Yerevan' | 'Asia/Kabul' | 'Antarctica/Mawson' | 'Asia/Yekaterinburg' | 'Asia/Karachi' | 'Asia/Kolkata' | 'Asia/Colombo' | 'Asia/Kathmandu' | 'Antarctica/Vostok' | 'Asia/Dhaka' | 'Asia/Rangoon' | 'Antarctica/Davis' | 'Asia/Novokuznetsk' | 'Asia/Hong_Kong' | 'Asia/Krasnoyarsk' | 'Asia/Brunei' | 'Australia/Perth' | 'Asia/Taipei' | 'Asia/Choibalsan' | 'Asia/Irkutsk' | 'Asia/Dili' | 'Asia/Pyongyang' | 'Australia/Adelaide' | 'Australia/Darwin' | 'Australia/Brisbane' | 'Australia/Melbourne' | 'Antarctica/DumontDUrville' | 'Australia/Currie' | 'Asia/Chita' | 'Antarctica/Macquarie' | 'Asia/Sakhalin' | 'Pacific/Auckland' | 'Etc/GMT-12' | 'Pacific/Fiji' | 'Asia/Anadyr' | 'Asia/Kamchatka' | 'Etc/GMT-13' | 'Pacific/Apia' — Timezone in which the schedule is set, in IANA timezone format. - `type` 1 | 2, required — Whether the inbox placement test is a one-time test or an automated test - `sending_method` 1 | 2, required — Whether the inbox placement test will be sent from Instantly or from outside Instantly - `campaign_id` string, uuid, nullable — Campaign ID - `email_subject` string, required — Email subject of the inbox placement test - `email_body` string, required — Email body of the inbox placement test - `emails` string[], required — Emails to send the inbox placement test to - `test_code` string, 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. - `tags` string[], nullable — List of tag IDs to use for sending emails - `text_only` boolean, nullable — Disables open tracking - `recipients` string[], required - `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 - `region` string, required — The region to send emails to - `sub_region` string, required — The sub-region to send emails to - `type` string, required — The type of email to send - `esp` string, required — The Email Service Provider (ESP) to send emails to - `timestamp_created` string, required — Timestamp when the inbox placement test was created - `timestamp_next_run` string, nullable — Timestamp when the inbox placement test will run next - `automations` object[], nullable — Optional automations to trigger based on conditions - `when` object, required - `condition` 'placement_goes_below' | 'placement_goes_above' | 'added_to_blacklists' | 'removed_from_blacklists', required — Condition for automation trigger - `condition_value` number, nullable — Value for condition, if applicable - `then` object, required — Actions to take when condition is met - `webhook_url` string - `pause_sending_campaigns_for` number — Number of days to pause sending campaigns for - `pause` boolean - `enable_slow_ramp` boolean - `disable_slow_ramp` boolean - `add_tags` string[] - `remove_tags` string[] - `status` 1 | 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. ## Other responses - `400` — Invalid request body (e.g. missing required fields, or invalid field values) - `401` — This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) - `402` — This request cannot be fulfilled because the workspace does not have an active paid plan - `404` — The requested resource was not found - `429` — You have exceeded the rate limit. Please check the rate limit docs for more information. --- [API](https://skmtc.net/instantly/apis/api-explorer.md) · [All operations](https://skmtc.net/instantly/apis/api-explorer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/instantly/api-explorer/revisions/378d1e253fe7/schema)