Segments

Create dynamic audience segments based on contact attributes, behavior, and engagement data.

GET

/segments

List all segments with optional filtering and pagination.

Query Parameters

Name	Type	Required	Description
search	string	Optional	Search segments by name.
limit	integer	Optional	Number of segments to return (default: 100, max: 1000).
offset	integer	Optional	Number of segments to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/segments?search=vip&limit=10" \
  -H "Authorization: Bearer tm_live_abc123"

GET

/segments/:id

Retrieve a single segment by ID.

curl https://api.topmail.so/api/v1/segments/SEGMENT_ID \
  -H "Authorization: Bearer tm_live_abc123"

POST

/segments

Create a new segment.

Request Body

Name	Type	Required	Description
name	string	Required	Segment name (max 100 characters).
conditions	object	Optional	Segment conditions with match mode ("all" or "any") and an array of rules.

curl -X POST https://api.topmail.so/api/v1/segments \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engaged Subscribers",
    "conditions": {
      "match": "all",
      "rules": [
        {"field": "engagement_score", "operator": "gte", "value": 50},
        {"field": "subscribed", "operator": "equals", "value": true}
      ]
    }
  }'

PATCH

/segments/:id

Update a segment. Only provided fields are modified.

Request Body

Name	Type	Required	Description
name	string	Optional	Updated segment name.
conditions	object	Optional	Updated segment conditions.

curl -X PATCH https://api.topmail.so/api/v1/segments/SEGMENT_ID \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Top Engaged Subscribers"}'

DELETE

/segments/:id

Permanently delete a segment.

curl -X DELETE https://api.topmail.so/api/v1/segments/SEGMENT_ID \
  -H "Authorization: Bearer tm_live_abc123"

POST

/segments/:id/estimate

Get an estimated count of contacts matching the segment conditions.

curl -X POST https://api.topmail.so/api/v1/segments/SEGMENT_ID/estimate \
  -H "Authorization: Bearer tm_live_abc123"

GET

/segments/:id/contacts

List contacts matching the segment conditions with pagination.

Query Parameters

Name	Type	Required	Description
limit	integer	Optional	Number of contacts to return (default: 100, max: 1000).
offset	integer	Optional	Number of contacts to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/segments/SEGMENT_ID/contacts?limit=50" \
  -H "Authorization: Bearer tm_live_abc123"

Condition Operators

Segment conditions support the following operators for building rules:

equalsExact match

not_equalsNot equal

containsString contains

gtGreater than

ltLess than

gteGreater than or equal

lteLess than or equal

in_last_daysWithin N days

more_than_days_agoOlder than N days

exactly_days_agoExactly N days ago

is_setField has a value

is_not_setField is empty

in_listValue in array

not_in_listValue not in array