EmailSendX Docs
EmailSendX Docs
/
Docs/API Reference/Segments

Segments API

Segments are dynamic, filter-based audiences that update automatically as contact data changes. Use the API to read segment definitions and member counts for reporting and external tooling.

The Segment Object

A segment is a saved set of filter conditions that dynamically calculates which contacts match. Segments are created and managed in the dashboard — the API provides read access.

json
{
  "id": "clx_seg_high_engage_id",
  "name": "High-Engagement Users",
  "description": "Opened at least 3 campaigns in last 90 days",
  "matchType": "all",
  "filters": [
    {
      "field": "opens_count",
      "operator": "gte",
      "value": 3
    },
    {
      "field": "last_open_at",
      "operator": "within_days",
      "value": 90
    }
  ],
  "cachedCount": 1248,
  "lastCountedAt": "2026-01-20T14:00:00Z",
  "createdAt": "2026-01-05T11:00:00Z"
}
FieldTypeDescription
idstringUnique segment identifier (CUID)
namestringHuman-readable segment name
descriptionstringOptional description of the segment criteria
matchTypeenum"all" (AND logic) or "any" (OR logic) for the filter conditions
filtersarrayArray of filter condition objects defining segment membership
cachedCountintegerCached member count — recalculated periodically
lastCountedAtstringISO 8601 timestamp when cachedCount was last recalculated
createdAtstringISO 8601 creation timestamp

Filter Conditions

Each segment has a filters array containing one or more condition objects. The matchType field determines whether all conditions must match (all) or any single condition is sufficient (any).

OperatorDescription
eqEquals
neqDoes not equal
gtGreater than
gteGreater than or equal to
ltLess than
lteLess than or equal to
containsString contains (metadata fields)
within_daysDate field is within the last N days
existsField exists and is not null
not_existsField is null or does not exist

Endpoints

Segments are read-only via API

Segment creation and editing is currently done in the dashboard (Contacts → Segments). The API provides read access to your existing segments, including their definitions and cached member counts.

List Segments

GET/api/v1/segmentsscope: segments:read

Returns a paginated list of all segments in the workspace. Pass an id query parameter to retrieve a single segment by ID.

Parameters

NameTypeInRequiredDescription
pageintegerqueryoptionalPage number (default: 1)
limitintegerqueryoptionalResults per page, max 100 (default: 50)
idstringqueryoptionalReturn a single segment by its ID

Response

json
{
  "data": [
    {
      "id": "clx_seg_high_engage_id",
      "name": "High-Engagement Users",
      "description": "Opened at least 3 campaigns in last 90 days",
      "matchType": "all",
      "filters": [
        { "field": "opens_count", "operator": "gte", "value": 3 },
        { "field": "last_open_at", "operator": "within_days", "value": 90 }
      ],
      "cachedCount": 1248,
      "lastCountedAt": "2026-04-20T14:00:00Z",
      "createdAt": "2026-01-05T11:00:00Z"
    },
    {
      "id": "clx_seg_churned_id",
      "name": "Churned Subscribers",
      "description": "No open in the last 180 days",
      "matchType": "all",
      "filters": [
        { "field": "last_open_at", "operator": "not_exists", "value": null }
      ],
      "cachedCount": 892,
      "lastCountedAt": "2026-04-20T14:00:00Z",
      "createdAt": "2026-02-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 12,
    "totalPages": 1
  }
}

Need to target dynamic audiences?

Build segments in the dashboard, then reference them by ID in your automations and campaigns.

View Lists APIView Contacts API