Campaigns

A campaign is a bulk send to a resolved audience. Every write endpoint here lists its prerequisites. See the Campaigns guide.

Base URL https://api.leadx.in/api/key/protected. Every request needs an apikey header — see Authentication.

17 endpoints.

`GET /campaign`

Get all campaigns.

Auth apikey

:::note Used by the web app pages/Campaign.jsx, pages/CreateCampaign.jsx, pages/ViewCampaign.jsx :::

Query parameters — the standard list contract: p, n, sortBy, sortOrder, searchBy, searchValue, filters, advancedFilters, ids, nids. See Pagination and Filtering.

Response — data is an array of Campaign objects, alongside the pagination fields described in Response format. segments, updatedBy, createdBy are populated, so they arrive as nested objects rather than ids.

`POST /campaign`

Create campaign.

Auth apikey · Success 201

:::note Used by the web app pages/Campaign.jsx, pages/CreateCampaign.jsx, pages/ViewCampaign.jsx :::

Prerequisites

An audience. At least one of segmentsBool, tagsBool, categoriesBool, contactsBool or customSegmentsBool must be true, with matching data — otherwise CampaignSegmentsRequired_400. Create whichever you will target: POST /segment · POST /tag · POST /contact-category · POST /contact
Confirm the audience resolves to somebody. An empty audience refuses creation with CampaignAudienceEmpty_400. POST /campaign/audience-preview
A template for the channel named in type. WhatsApp templates must be approved by Meta before a campaign can use them. POST /template/email · POST /template/whatsapp · POST /template/whatsapp/status-reconcile
A sending app, passed as smtp: { id }. Required at start time for type: "email" — CampaignSMTPRequired_400. POST /apps/smtp · POST /apps/ses · POST /apps/sendgrid · GET /apps/smtp

Request body

Field	Default	Notes
`name`	—	Must be unique for the company — otherwise `CampaignNameAlreadyExists_400`.
`type`	—	The channel: `email`, `whatsapp`, and the other configured channels.
`description`	`""`
`template`	—	Template id for that channel.
`segments`	`[]`	Segment ids. Only read when `segmentsBool` is `true`.
`smtp`	—	`{ id }` of the sending configuration. Required at start time for `email`.
`intervalMs`	—	Delay between individual sends, in milliseconds — for provider rate limits.
`daysOfWeek`	—	Days the campaign may send on. `0`–`6`, Sunday = `0`.
`timeWindow`	—	`{ start, end }` as `HH:MM`, to keep sends inside business hours.
`scheduleType`	—	How the campaign is scheduled.
`startAt`	—	ISO timestamp for the first send.
`endAt`	—	ISO timestamp after which nothing is sent.
`triggerWorkflow`	`true`	Whether sends emit workflow events. Set `false` so a large campaign does not trigger thousands of workflow runs.
`startCampaign`	`false`	Start immediately. `false` creates it idle.
`customAudience`	—	Inline audience: `tags`, `categories`, `contacts`, or an advanced filter.
`customSegmentsBool`	`false`	Target an inline advanced-filter audience.
`segmentsBool`	`false`	Target saved segments.
`tagsBool`	`false`	Target contacts carrying `customAudience.tags`.
`categoriesBool`	`false`	Target contacts in `customAudience.categories`.
`contactsBool`	`false`	Target the explicit list in `customAudience.contacts`.

Required: name, type.

Errors CampaignAudienceEmpty_400 · CampaignNameAlreadyExists_400 · CampaignSMTPNotBelongToCompany_400 · CampaignSMTPNotFound_400 · CampaignSMTPRequired_400 · CampaignSegmentNotFound_400 · CampaignSegmentsRequired_400

`DELETE /campaign`

Delete campaigns.

Auth apikey · Success 200

:::note Used by the web app pages/Campaign.jsx, pages/CreateCampaign.jsx, pages/ViewCampaign.jsx :::

Request body — the standard bulk selection: ids, nids, selectAll. Query-string filters apply when selectAll is set.

Response — data is null; the outcome is the status code and message.

`GET /campaign/:id`

Get campaign.

Auth apikey

:::note Used by the web app components/CampaignSetup.jsx, components/ContentMessaging.jsx, components/ScheduleDelivery.jsx and 4 more :::

Path parameters

Name
`id`	Required

Response — data is one Campaign object.

Errors CampaignNotFound_404 · UnsupportedCampaignType_400

`PUT /campaign/:id`

Update campaign.

Auth apikey

:::note Used by the web app components/CampaignSetup.jsx, components/ContentMessaging.jsx, components/ScheduleDelivery.jsx and 4 more :::

Prerequisites

An existing campaign. A campaign that has already started may refuse edits with CampaignCannotBeUpdated_400. GET /campaign · POST /campaign

Path parameters

Name
`id`	Required

Request body

Field	Default
`startCampaign`	—

Response — data is one Campaign object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignCannotBeUpdated_400 · CampaignNotFound_404 · CampaignSegmentsRequired_400

`POST /campaign/:id/assignTag`

Assign tag to failed contacts.

Auth apikey · Success 200

:::note Used by the web app pages/ManualCampaignDetail.jsx, pages/ViewCampaign.jsx :::

Prerequisites

A campaign with failed recipients, and a tag to assign them. GET /campaign/:id/recipients · POST /tag

Path parameters

Name
`id`	Required

Request body

Field	Default
`name`	—

Required: name.

Response — data is one Campaign object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignNotFound_404 · NoCampaignSelected_400 · TagNameAlreadyExists_400

`PUT /campaign/:id/continue`

Failed to active.

Auth apikey

:::note Used by the web app pages/Campaign.jsx :::

Prerequisites

A campaign in a failed state. Repeated failures are refused with CampaignFailedManyTime_400. GET /campaign

Path parameters

Name
`id`	Required

Response — data is one ResponseMessage object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignCannotBeUpdated_400 · CampaignFailedManyTime_400 · CampaignNotFound_404

`GET /campaign/:id/logs`

Get all campaign logs.

Auth apikey

:::note Used by the web app pages/ViewCampaign.jsx :::

Prerequisites

A campaign that has run. GET /campaign · PUT /campaign/:id/play-pause

Path parameters

Name
`id`	Required

Query parameters — the standard list contract: p, n, sortBy, sortOrder, searchBy, searchValue, filters, advancedFilters, ids, nids. See Pagination and Filtering.

Response — data is an array of UnifiedMessage objects, alongside the pagination fields described in Response format. contact, template, app, updatedBy, createdBy are populated, so they arrive as nested objects rather than ids.

Errors CampaignNotFound_404

`PUT /campaign/:id/play-pause`

Toggle campaign play pause.

Auth apikey · Success 200

:::note Used by the web app pages/Campaign.jsx :::

Prerequisites

An existing campaign. For type: "email" a sending app must be attached before it can start. POST /campaign · GET /apps/smtp

Path parameters

Name
`id`	Required

Response — data is one Campaign object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignCannotBeUpdated_400 · CampaignNotFound_404

`GET /campaign/:id/recipients`

Per-recipient send report from the v2 engine.

Auth apikey

Prerequisites

A campaign that has started. Recipients are materialised at start time by the v2 engine, so a campaign created but never started has none. PUT /campaign/:id/play-pause · POST /campaign

Path parameters

Name
`id`	Required

Query parameters

Field	Default
`status`	—
`page`	`1`
`limit`	`50`

Response — data is one Campaign object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignNotFound_404

`POST /campaign/:id/retry-failed`

Retry failed campaign.

Auth apikey · Success 201

:::note Used by the web app pages/Campaign.jsx :::

Prerequisites

A campaign with failed recipients. Check the report first. GET /campaign/:id/recipients

Path parameters

Name
`id`	Required

Response — data is one SendJob object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignNotFound_404 · NoCampaignSelected_400

`POST /campaign/:id/sync-failed`

Failed contacts sync.

Auth apikey · Success 200

:::note Used by the web app pages/ViewCampaign.jsx :::

Prerequisites

A campaign with failed recipients. GET /campaign/:id/recipients

Path parameters

Name
`id`	Required

Response — data is one ResponseMessage object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors CampaignNotFound_404 · NoMessagesSent_400

`POST /campaign/audience-preview`

Resolve an audience selection to a contact count, without creating anything.

Auth apikey

Prerequisites

Something to select. Send the same audience flags and data you intend to give POST /campaign. POST /segment · POST /tag · POST /contact-category · POST /contact

Request body

Field	Default
`segments`	`[]`
`customAudience`	`{}`

`GET /campaign/manual`

Get all manual campaigns.

Auth apikey

Query parameters — the standard list contract: p, n, sortBy, sortOrder, searchBy, searchValue, filters, advancedFilters, ids, nids. See Pagination and Filtering.

Response — data is an array of TempManualCampaign objects, alongside the pagination fields described in Response format. updatedBy, createdBy are populated, so they arrive as nested objects rather than ids.

`POST /campaign/manual`

Manual campaign temp.

Auth apikey

Prerequisites

A template. POST /template/email · POST /template/whatsapp
A sending app. GET /apps/smtp
Contacts to send to. POST /contact · GET /contact

Request body

Field	Default
`templateId`	—
`columnMapping`	—
`templateName`	—
`templateSubject`	—
`campaignType`	—
`campaignName`	—
`file`	—
`delaySeconds`	`0`

Response — data is one ResponseMessage object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors InvalidCampaignType_400 · InvalidMapping_400 · InvalidPayload_400 · NoFile_400 · TemplateNotFound_404

`GET /campaign/manual/:id`

Get manual campaigns.

Auth apikey

:::note Used by the web app pages/ManualCampaign.jsx :::

Path parameters

Name
`id`	Required

Response — data is one TempManualCampaign object.

Errors ManualCampaignNotFound_404

`POST /campaign/test/:type`

Send a test message without touching the audience.

Auth apikey · Success 200

Prerequisites

A template to render. POST /template/email · POST /template/whatsapp
A sending app to send through. GET /apps/smtp

Path parameters

Name
`type`	Required

Request body

Field	Default
`smtp`	—
`template`	—
`testEmail`	—
`testContactNumber`	`{}`

Response — data is one EmailTemplate object. (Resource deduced from the collections this handler reads, not read off an explicit return.)

Errors EmailSendingFailed_500 · EmailTemplateNotFound_404 · InvalidCampaignType_400 · MetaTemplateNotFound_404

GET /campaign​

POST /campaign​

DELETE /campaign​

GET /campaign/:id​

PUT /campaign/:id​

POST /campaign/:id/assignTag​

PUT /campaign/:id/continue​

GET /campaign/:id/logs​

PUT /campaign/:id/play-pause​

GET /campaign/:id/recipients​

POST /campaign/:id/retry-failed​

POST /campaign/:id/sync-failed​

POST /campaign/audience-preview​

GET /campaign/manual​

POST /campaign/manual​

GET /campaign/manual/:id​

POST /campaign/test/:type​

`GET /campaign`

`POST /campaign`

`DELETE /campaign`

`GET /campaign/:id`

`PUT /campaign/:id`

`POST /campaign/:id/assignTag`

`PUT /campaign/:id/continue`

`GET /campaign/:id/logs`

`PUT /campaign/:id/play-pause`

`GET /campaign/:id/recipients`

`POST /campaign/:id/retry-failed`

`POST /campaign/:id/sync-failed`

`POST /campaign/audience-preview`

`GET /campaign/manual`

`POST /campaign/manual`

`GET /campaign/manual/:id`

`POST /campaign/test/:type`