Skip to main content
POST
/
campaigns
/
v2
Create campaign
curl --request POST \
  --url https://inboxapp.com/api/v1/campaigns/v2 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "accountLinkIds": [
    "<string>"
  ],
  "rules": {
    "syncedListIds": [
      "<string>"
    ],
    "excludedListIds": [
      "<string>"
    ],
    "excludeContacted": true,
    "excludeMutuals": true,
    "columnMappings": {}
  },
  "scheduleTimezone": "UTC"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "description": "Targeting SaaS founders from the import list",
  "enabled": true,
  "dryRun": true,
  "targetsCount": 4503599627370495,
  "contactedCount": 4503599627370495,
  "repliesCount": 4503599627370495,
  "completionRate": 123,
  "replyRate": 123,
  "hourlyMessageRate": 13,
  "scheduleTimezone": "<string>",
  "scheduleHours": {},
  "isBuildingPlan": true,
  "isSyncing": true,
  "scopeAssessedCount": 4503599627370495,
  "accountLinkIds": [
    "<string>"
  ],
  "rules": {
    "syncedLists": [
      {
        "listId": "<string>",
        "listName": "<string>",
        "columnMapping": {
          "custom_q5cktl47a6pqa74eu06fz89v": "custom_m8r2xj93hd5bk0atcw7oe4fp"
        }
      }
    ],
    "excludedLists": [
      {
        "listId": "<string>",
        "listName": "<string>"
      }
    ],
    "excludeContacted": true,
    "excludeMutuals": true
  },
  "sequence": {
    "version": 123,
    "steps": [
      {
        "id": "<string>",
        "rank": 123,
        "data": {
          "segments": [
            {
              "type": "<unknown>",
              "text": "<string>"
            }
          ]
        }
      }
    ]
  },
  "automations": [
    {
      "id": "<string>",
      "trigger": "<unknown>",
      "actionData": {
        "statusId": "<string>"
      },
      "enabled": true
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "pausedAt": "2025-06-05T16:00:00.000Z",
  "completedAt": null,
  "lastStartedAt": "2025-06-03T09:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
name
string
required

Display name for the campaign

Required string length: 1 - 255
Example:

"Q1 outreach"

​
accountLinkIds
string[]
required

Account link IDs to send messages from. At least one is required.

Pattern: ^[0-9a-z]+$
Example:
["r4t9vw15jm6bn3yxcf2dq8ek"]
​
rules
object

Optional lead rules to apply at creation. Configures which lists to sync leads from and which to exclude.

​
scheduleTimezone
string
default:UTC

IANA timezone for the sending schedule

Examples:

"UTC"

"America/New_York"

Response

200 - application/json

OK

​
id
string
required

Unique identifier for the campaign

Pattern: ^[0-9a-z]+$
Example:

"usdjpdql3f90seqk13rwuo7z"

​
name
string
required

Display name of the campaign

Example:

"Q1 DM outreach"

​
description
string | null
required

Optional description for the campaign

Example:

"Targeting SaaS founders from the import list"

​
status
enum<string>
required

Current lifecycle status of the campaign.

Available options:
draft,
active,
paused,
completed
Example:

"paused"

​
enabled
boolean
required

Whether the campaign is enabled for sending. Enabling a draft campaign transitions it to active. Disabling any campaign transitions it to paused.

Example:

true

​
dryRun
boolean
required

When true, the campaign simulates sending without delivering real messages. This flag is managed internally and cannot be set through the API.

Example:

false

​
targetsCount
integer
required

Total number of leads in scope for this campaign

Required range: 0 <= x <= 9007199254740991
Example:

1200

​
contactedCount
integer
required

Number of leads that have been contacted so far

Required range: 0 <= x <= 9007199254740991
Example:

340

​
repliesCount
integer
required

Number of leads that replied to a campaign message

Required range: 0 <= x <= 9007199254740991
Example:

42

​
completionRate
number
required

Fraction of targeted leads that have fully completed their sequence (0-1)

Example:

0.28

​
replyRate
number
required

Fraction of contacted leads that replied (0-1). Zero when no leads have been contacted.

Example:

0.12

​
hourlyMessageRate
integer
required

Messages to send per hour per linked account

Required range: 1 <= x <= 25
Example:

8

​
scheduleTimezone
string
required

IANA timezone used for the sending schedule windows

Example:

"America/New_York"

​
scheduleHours
object
required

Sending windows per day of week where key 0 is Sunday and values are minute-of-day start/end ranges

Example:
{
  "1": { "start": 540, "end": 1020 },
  "2": { "start": 540, "end": 1020 },
  "3": { "start": 540, "end": 1020 },
  "4": { "start": 540, "end": 1020 },
  "5": { "start": 540, "end": 1020 }
}
​
isBuildingPlan
boolean
required

True while the campaign is rebalancing lead assignments across sending accounts. This runs automatically in the background and does not block sending or any other operations.

Example:

false

​
isSyncing
boolean
required

True while the campaign is updating its lead list based on the current rules. This runs automatically in the background after rule changes.

Example:

false

​
scopeAssessedCount
integer
required

Number of leads that have been assessed for eligibility. If this number is less than targetsCount, some leads are still being evaluated for reachability and the target count may increase. Once scopeAssessedCount equals targetsCount, the final scope of the campaign is known.

Required range: 0 <= x <= 9007199254740991
Example:

1150

​
accountLinkIds
string[]
required

IDs of linked accounts used to send campaign messages

Pattern: ^[0-9a-z]+$
Example:
["r4t9vw15jm6bn3yxcf2dq8ek"]
​
rules
object
required

Lead rules controlling which lists feed leads into the campaign and which lists are excluded.

​
sequence
object
required

The current message sequence — the ordered steps sent to each lead.

​
automations
object[]
required

Automations that trigger actions on certain events, such as setting a status when a prospect replies.

​
createdAt
string<date-time>
required

When the campaign was created

Example:

"2025-06-01T12:00:00.000Z"

​
updatedAt
string<date-time>
required

When the campaign was last modified

Example:

"2025-06-02T09:30:00.000Z"

​
pausedAt
string<date-time> | null
required

When the campaign was last paused, or null if never paused

Example:

"2025-06-05T16:00:00.000Z"

​
completedAt
string<date-time> | null
required

When the campaign finished processing all targets, or null if still running

Example:

null

​
lastStartedAt
string<date-time> | null
required

When the campaign was most recently started or resumed, or null if never started

Example:

"2025-06-03T09:00:00.000Z"