> ## Documentation Index
> Fetch the complete documentation index at: https://api.smartlead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Deliverability Test

> Create a manual or automated deliverability test for a campaign email

> [!NOTE]
>
> **Smart Delivery v2 (Deliverability Test) API**: the deliverability (inbox placement) test that sends your campaign email to seed inboxes and reports where it landed. Contact [support@smartlead.ai](mailto:support@smartlead.ai) for access.

## Overview

Creates a Smart Delivery v2 (Deliverability Test) test: it sends the chosen sequence email from your sender mailboxes to seed inboxes at the chosen providers, then reports whether each email landed in the inbox, a tab or spam. A `MANUAL` test starts one run immediately; an `AUTO` test starts runs on its `schedule`. Each run uses one run credit.

`schedule` is one of:

* `{ "frequency": "DAILY", "timeOfDay": "09:00", "timezone": "America/New_York" }`
* `{ "frequency": "WEEKLY", "weekdays": [1, 3, 5], "timeOfDay": "09:00", "timezone": "America/New_York" }` (`weekdays` are numbers 1 to 7)
* `{ "frequency": "EVERY_N_DAYS", "everyNDays": 3, "timeOfDay": "09:00", "timezone": "America/New_York" }` (`everyNDays` 2 to 90)

`timeOfDay` is `HH:mm` (24 hours) and `timezone` an IANA timezone name.

## Query Parameters

**api\_key** `string` *required*

Your SmartLead API key

## Body Parameters

**type** `string` *required*

`MANUAL` (one run, started now) or `AUTO` (recurring runs)

**name** `string` *required*

Test name, up to 200 characters

**description** `string`

Up to 2000 characters

**folderId** `number`

Folder to put the test in

**campaignId** `number` *required*

Smartlead campaign whose email is tested

**sequenceId** `number` *required*

Sequence step to test

**variantId** `number | null`

A/B variant to test. Leave out for a step without variants

**providerIds** `number[]` *required*

1 to 20 provider IDs from [List Seed Providers](https://api.smartlead.ai/api-reference/smart-delivery-v2/providers.md), no duplicates

**emailAccountIds** `number[]` *required*

1 to 1000 Smartlead email account IDs to send from. They must be attached to the campaign, and your plan limits how many one test may use (see [Get Plan Limits](https://api.smartlead.ai/api-reference/smart-delivery-v2/limits.md))

**sendAllAtOnce** `boolean`

`true` to send every email of a run together. Set this or `sendGap`, not both

**sendGap** `object`

Spread the emails out: `{ "amount": 10, "unit": "minutes" }` with `unit` one of `minutes`, `hours`, `days`. At least 5 minutes and at most 30 days

**textOnly** `boolean`

Send the emails as text only (no HTML). Overrides the campaign's HTML and tracking settings

**schedule** `object`

`AUTO` only, required: when runs start (see below)

**startsAt** `string`

`AUTO` only, required: first run time (ISO 8601, in the future)

**endsAt** `string`

`AUTO` only: no run starts after this time. Use this or `maxRuns`, not both

**maxRuns** `number`

`AUTO` only: stop after this many runs (1 to 1000)

```bash cURL theme={null}
curl -X POST "https://sl-sd-api.smartlead.ai/api/v1/smart-delivery/tests?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "MANUAL", "name": "Q4 Outbound - sequence step 1", "campaignId": 5614, "sequenceId": 20311, "providerIds": [2, 4], "emailAccountIds": [88101, 88102], "sendAllAtOnce": true}'
```

```python Python theme={null}
import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://sl-sd-api.smartlead.ai/api/v1/smart-delivery/tests",
    params={"api_key": API_KEY}, json={"type": "MANUAL", "name": "Q4 Outbound - sequence step 1", "campaignId": 5614, "sequenceId": 20311, "providerIds": [2, 4], "emailAccountIds": [88101, 88102], "sendAllAtOnce": true}
)
print(response.status_code)
print(response.json())
```

```javascript JavaScript theme={null}
const API_KEY = 'YOUR_API_KEY';

const response = await fetch(
  `https://sl-sd-api.smartlead.ai/api/v1/smart-delivery/tests?api_key=${API_KEY}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({"type": "MANUAL", "name": "Q4 Outbound - sequence step 1", "campaignId": 5614, "sequenceId": 20311, "providerIds": [2, 4], "emailAccountIds": [88101, 88102], "sendAllAtOnce": true})
  }
);
console.log(await response.json());
```

## Response Fields

**test** `object`

The created test

**test**

**id** `string`

Test ID (UUID). Use it in every `/tests/{id}` path.

**name** `string`

Test name

**description** `string | null`

Test description

**type** `string`

`MANUAL` (one run, started now) or `AUTO` (recurring runs on a schedule)

**status** `string`

`ACTIVE`, `PAUSED`, `COMPLETED` or `STOPPED`

**statusReason** `string | null`

Why the test is in this status, for example `USER_PAUSED`, `USER_STOPPED` or `SCHEDULE_ENDED`

**folderId** `number | null`

Folder the test is in

**campaignId** `number`

Smartlead campaign whose email is tested

**sequenceId** `number`

Sequence step that is tested

**variantId** `number | null`

A/B variant tested, or `null` for the step's base email

**seedsPerSenderPerProvider** `number`

Seed inboxes each sender mails per provider

**sendAllAtOnce** `boolean`

`true` when all emails of a run go out together, `false` when they are spread by `sendGapMinutes`

**sendGapMinutes** `number | null`

Minutes between emails when they are spread out

**textOnly** `boolean`

Whether the emails are sent as text only (no HTML)

**schedule** `object | null`

`AUTO` tests: the schedule (see Create Deliverability Test)

**startsAt** `string | null`

`AUTO` tests: first run time (ISO 8601)

**endsAt** `string | null`

`AUTO` tests: the date after which no run starts

**maxRuns** `number | null`

`AUTO` tests: the number of runs after which the test completes

**nextRunAt** `string | null`

`AUTO` tests: when the next run starts

**runsCreated** `number`

Runs created so far

**createdAt** `string`

Creation time (ISO 8601)

**run** `object | null`

The first run, for a `MANUAL` test. `null` for an `AUTO` test that starts later.

**run**

**id** `string`

Run ID (UUID)

**runNo** `number`

Run number within the test, starting at 1

**status** `string`

`QUEUED`, `SENDING`, `COLLECTING`, `COMPLETED`, `FAILED`, `SKIPPED` or `CANCELLED`

**statusReason** `string | null`

Why a run failed, was skipped or cancelled

**scheduledFor** `string`

When the run was due to start

**contentSnapshot** `object | null`

The email content that was sent (subject, body and the lead used for merge tags)

**skippedSenders** `array | null`

Senders left out of the run, with the reason

**seedFallback** `boolean`

`true` when some emails went to a different seed than first planned

**completedAt** `string | null`

When the run completed

**createdAt** `string`

Creation time

## Response Codes

**201** `Success`

Success

**402** `Error`

No Smart Delivery plan, or no run credits left

**404** `Error`

The campaign or variant does not exist (`VARIANT_NOT_FOUND`)

**422** `Error`

Invalid provider (`INVALID_PROVIDER`), senders not attached to the campaign (`INVALID_SENDERS`), too many senders for your plan (`SENDER_LIMIT`), `startsAt` in the past (`STARTS_AT_IN_PAST`), or a schedule with no run before `endsAt` (`SCHEDULE_HAS_NO_RUNS`)

**401** `Unauthorized`

Missing, invalid or expired API key (`UNAUTHORIZED`)

**403** `Forbidden`

Client (agency) API keys are not allowed (`CLIENT_NOT_ALLOWED`), or your plan does not include API access (`API_ACCESS_RESTRICTED`)

**429** `Too Many Requests`

Too many requests for this API key. Wait the number of seconds in the `Retry-After` header (`RATE_LIMITED`)

```json 201 - Success theme={null}
{
  "test": {
    "id": "3f2b8c1e-5d4a-4e7b-9a60-1c2d3e4f5a6b",
    "name": "Q4 Outbound - sequence step 1",
    "description": null,
    "type": "MANUAL",
    "status": "ACTIVE",
    "statusReason": null,
    "folderId": null,
    "campaignId": 5614,
    "sequenceId": 20311,
    "variantId": null,
    "seedsPerSenderPerProvider": 4,
    "sendAllAtOnce": true,
    "sendGapMinutes": null,
    "textOnly": false,
    "schedule": null,
    "startsAt": null,
    "endsAt": null,
    "maxRuns": null,
    "nextRunAt": null,
    "runsCreated": 1,
    "createdAt": "2026-11-17T08:30:00.000Z"
  },
  "run": {
    "id": "8a1c7e90-2b3d-4c5e-8f60-7a9b0c1d2e3f",
    "runNo": 1,
    "status": "QUEUED",
    "statusReason": null,
    "scheduledFor": "2026-11-17T08:30:00.000Z",
    "contentSnapshot": { "subject": "Quick question, {{first_name}}", "body": "..." },
    "skippedSenders": null,
    "seedFallback": false,
    "completedAt": null,
    "createdAt": "2026-11-17T08:30:00.000Z"
  }
}
```

```json Error - Unauthorized theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API Key"
  }
}
```

## Related Endpoints

* [List Seed Providers](https://api.smartlead.ai/api-reference/smart-delivery-v2/providers.md)
* [Get Plan Limits](https://api.smartlead.ai/api-reference/smart-delivery-v2/limits.md)
* [List Deliverability Tests](https://api.smartlead.ai/api-reference/smart-delivery-v2/list-tests.md)
* [Get Deliverability Test](https://api.smartlead.ai/api-reference/smart-delivery-v2/get-test.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.