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": "AUTOMATED",
    "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": "AUTOMATED",
  "workflow": {
    "nodes": [...],
    "edges": [...]
  },
  "settings": {
    "frequencyCap": 3,
    "quietHours": { "start": "22:00", "end": "08:00" }
  },
  "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	Yes	`AUTOMATED`, `BROADCAST`, etc.
`workflow`	object	Yes	Visual workflow graph (nodes + edges)
`settings`	object	No	Frequency caps, quiet hours, etc.
`startAt`	string	No	Scheduled start time
`endAt`	string	No	Scheduled end time

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`
`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)