Campaigns

Campaigns are multi-channel automated workflows that send messages to contacts based on triggers, conditions, and actions.

List Campaigns

`GET /api/workspaces/{workspaceId}/campaigns`

Returns all campaigns with enrollment and message counts.

Auth: Session required

Response:


[
  {
    "id": "cmp_abc123",
    "name": "Welcome Series",
    "status": "ACTIVE",
    "type": "AUTOMATION",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "triggers": [...],
    "_count": {
      "enrollments": 5000,
      "messages": 12000
    }
  }
]

Create Campaign

`POST /api/workspaces/{workspaceId}/campaigns`

Auth: Session required

Request Body:


{
  "name": "Welcome Series",
  "description": "Onboarding email sequence for new signups",
  "type": "AUTOMATION",
  "workflow": {
    "nodes": [...],
    "edges": [...]
  },
  "settings": {
    "frequencyCap": { "maxMessages": 3, "windowMs": 86400000 },
    "quietHours": { "enabled": true, "startHour": 22, "endHour": 8, "timezone": "UTC" },
    "reEntryAllowed": false,
    "priority": "NORMAL"
  },
  "startAt": "2026-02-01T00:00:00.000Z",
  "endAt": "2026-03-01T00:00:00.000Z"
}

Field	Type	Required	Description
`name`	string	Yes	Campaign name
`description`	string	No	Description
`type`	string	No	`AUTOMATION` (default), `BROADCAST`, `AB_TEST`, or `TRANSACTIONAL`
`workflow`	object	No	Visual workflow graph (nodes + edges)
`settings`	object	No	See Campaign Settings
`startAt`	string	No	Scheduled start time
`endAt`	string	No	Scheduled end time

Campaign Settings

Field	Type	Default	Description
`frequencyCap.maxMessages`	number	`0` (unlimited)	Max messages per contact within the window
`frequencyCap.windowMs`	number	`86400000`	Frequency cap window in milliseconds
`quietHours.enabled`	boolean	`false`	Suppress sends during quiet hours
`quietHours.startHour` / `quietHours.endHour`	number (0–23)	`22` / `8`	Quiet window bounds
`quietHours.timezone`	string	`"UTC"`	IANA timezone for quiet hours
`entryLimit`	number	—	Max number of enrollments for the campaign
`reEntryAllowed`	boolean	`false`	Allow contacts to be enrolled again after completing
`reEntryCooldownMs`	number	—	Minimum time between re-entries
`goal.eventType`	string	—	Event that counts as a conversion
`goal.attributionWindowMs`	number	`604800000`	Attribution window for the goal
`goal.autoComplete`	boolean	`true`	Complete the enrollment when the goal is reached
`priority`	string	`"NORMAL"`	`LOW`, `NORMAL`, `HIGH`, or `URGENT`

Get Campaign

`GET /api/workspaces/{workspaceId}/campaigns/{campaignId}`

Returns full campaign details including triggers, actions (ordered by position), A/B tests with variants, and enrollment/message counts.

Update Campaign

`PATCH /api/workspaces/{workspaceId}/campaigns/{campaignId}`

Partially updates campaign configuration or status.

Request Body: Any subset of name, description, status, type, workflow, settings, startAt, endAt.

Delete Campaign

`DELETE /api/workspaces/{workspaceId}/campaigns/{campaignId}`

Permanently deletes a campaign.

Execute Campaign

`POST /api/workspaces/{workspaceId}/campaigns/{campaignId}/execute`

Executes a campaign for a specific contact or processes a trigger.

Request Body:


{
  "action": "execute_for_contact",
  "contactId": "ct_abc123"
}

Or trigger-based:


{
  "action": "process_trigger",
  "triggerType": "SEGMENT_ENTRY",
  "segmentId": "seg_abc123"
}

Field	Type	Required	Description
`action`	string	Yes	`execute_for_contact` or `process_trigger`
`contactId`	string	Conditional	Required for `execute_for_contact`
`triggerType`	string	Conditional	`EVENT`, `SEGMENT_ENTRY`, `SEGMENT_EXIT`, `SCHEDULED`, `MANUAL`, `STAGE_CHANGE`
`segmentId`	string	No	For segment-based triggers
`eventType`	string	No	For event-based triggers

Enroll Contacts

`POST /api/workspaces/{workspaceId}/campaigns/{campaignId}/enroll`

Enrolls one or more contacts into an active campaign.

Request Body:


{
  "contactIds": ["ct_1", "ct_2", "ct_3"]
}

Response:


{
  "enrolled": 2,
  "alreadyEnrolled": 1,
  "errors": 0,
  "details": [
    { "contactId": "ct_1", "status": "enrolled" },
    { "contactId": "ct_2", "status": "enrolled" },
    { "contactId": "ct_3", "status": "already_enrolled" }
  ]
}

Campaign Workflow

The campaign workflow is a visual graph that consists of:

Trigger Nodes

Event — Fires when a contact triggers a specific event type
Segment Entry — Fires when a contact enters a segment
Segment Exit — Fires when a contact leaves a segment
Scheduled — Fires at a specific time
Manual — Manually triggered via API

Action Nodes

Send Message — Dispatches via email, push, Telegram, or on-site
Set Field — Updates a contact attribute
Add/Remove Tag — Manages contact tags
Webhook — Calls an external URL
Update Score — Adjusts the contact’s lead score
Notify Inbox — Creates an inbox thread for manual follow-up

Condition Nodes

Attribute Check — Branches based on contact attributes
Event Check — Branches based on event history
A/B Split — Randomly assigns contacts to variants

Delay Nodes

Short delays (seconds/minutes)
Long delays (hours/days)