Segments

Segments are dynamic audience groups computed from rules based on contact attributes, event history, channel availability, and consent state.

List Segments

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

Returns all segments with their active member counts.

Auth: Session required

Response:


[
  {
    "id": "seg_abc123",
    "name": "Active Users",
    "description": "Users who visited in the last 7 days",
    "rules": { ... },
    "evaluation": "DYNAMIC",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "_count": { "memberships": 1234 }
  }
]

Create Segment

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

Auth: Session required

Request Body:


{
  "name": "Active Users",
  "description": "Users who visited in the last 7 days",
  "rules": {
    "operator": "AND",
    "conditions": [
      {
        "type": "event",
        "eventType": "page_view",
        "timeWindow": "7d",
        "operator": "gte",
        "value": 1
      }
    ]
  },
  "evaluation": "DYNAMIC"
}

Field	Type	Required	Description
`name`	string	Yes	Segment name
`description`	string	No	Human-readable description
`rules`	object	Yes	Rule definition (see below)
`evaluation`	string	Yes	`DYNAMIC` or `STATIC`

Rule Structure

Rules use a nested condition tree with AND/OR operators:


{
  "operator": "AND",
  "conditions": [
    {
      "type": "attribute",
      "field": "attributes.plan",
      "operator": "eq",
      "value": "pro"
    },
    {
      "type": "event",
      "eventType": "purchase",
      "timeWindow": "30d",
      "operator": "gte",
      "value": 1
    },
    {
      "type": "channel",
      "channel": "EMAIL",
      "status": "OPTED_IN"
    }
  ]
}

Condition Types:

Type	Description
`attribute`	Match on contact profile attributes
`event`	Match on event history (type, count, time window)
`channel`	Match on channel availability / consent status
`tag`	Match on contact tags

Get Segment (Preview)

`GET /api/workspaces/{workspaceId}/segments/{segmentId}`

Returns segment details with total member count and up to 10 sample contacts.

Response:


{
  "segment": { "id": "seg_abc123", "name": "Active Users" },
  "totalMembers": 1234,
  "sampleContacts": [
    { "id": "ct_1", "email": "jane@example.com", "firstName": "Jane" }
  ]
}

Recompute Segment

`POST /api/workspaces/{workspaceId}/segments/{segmentId}`

Triggers a full recomputation of segment memberships.

Auth: Session required

Response:


{
  "segmentId": "seg_abc123",
  "added": 15,
  "removed": 3,
  "unchanged": 1216
}