Messages

Messages represent dispatched communications to contacts across all channels.

List Messages

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

Paginated list of messages with filtering.

Auth: Session required

Query Parameters:

Param	Type	Default	Description
`page`	number	1	Page number
`limit`	number	50	Items per page
`channel`	string	—	`EMAIL`, `PUSH`, `TELEGRAM`, `ONSITE`, `WEBHOOK`
`status`	string	—	`QUEUED`, `SENDING`, `SENT`, `DELIVERED`, `OPENED`, `CLICKED`, `BOUNCED`, `FAILED`, `UNSUBSCRIBED`
`contactId`	string	—	Filter by contact
`campaignId`	string	—	Filter by campaign

Response:


{
  "data": [
    {
      "id": "msg_abc123",
      "channel": "EMAIL",
      "status": "DELIVERED",
      "subject": "Welcome to Acme!",
      "sentAt": "2026-01-15T10:00:00.000Z",
      "openedAt": "2026-01-15T10:05:00.000Z",
      "contactId": "ct_1",
      "campaignId": "cmp_1"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 5000,
    "totalPages": 100
  }
}

Send Message

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

Sends a message to a contact through the specified channel.

Auth: Session required

Request Body:


{
  "contactId": "ct_abc123",
  "channel": "EMAIL",
  "subject": "Your weekly digest",
  "body": "<h1>Hello {{firstName}}</h1><p>Here is your update...</p>",
  "templateId": "tpl_abc123",
  "campaignId": "cmp_abc123",
  "metadata": { "category": "digest" }
}

Field	Type	Required	Description
`contactId`	string	Yes	Target contact ID
`channel`	string	Yes	`EMAIL`, `PUSH`, `TELEGRAM`, `ONSITE`, `WEBHOOK`
`subject`	string	No	Message subject (email)
`body`	string	No	Message body content
`templateId`	string	No	Template to render
`campaignId`	string	No	Associated campaign
`metadata`	object	No	Additional metadata

Response (200): Dispatch result. Returns 422 if dispatch fails.

Get Message

`GET /api/workspaces/{workspaceId}/messages/{messageId}`

Returns message details with contact, template, and campaign information.

Message Status Flow


QUEUED → SENDING → SENT → DELIVERED → OPENED → CLICKED
                                   ↘ BOUNCED
                                   ↘ FAILED
                                   ↘ UNSUBSCRIBED

Each status transition is tracked with timestamps and events.