Segments API

Saved subscriber filters. Cursor-paginated; pass updated_since with the synced_through value from your previous run to fetch only what changed.

The stored filter definition is not published — see the segment object. Use GET /segments/{segmentId}/count for the number of subscribers a segment matches.

Creates one saved subscriber filter. Names are NOT required to be unique — the app does not enforce it either — so two segments may share a name and are told apart by id.

The conditions definition is a strict, validated language, not free-form JSON: a group (operator: AND/OR) of conditions, nestable two levels. Each condition names a field, an operator and usually a value. Supported fields and their operators:

- email, name, firstName, lastName — equals, not_equals, contains, not_contains, starts_with, ends_with; is_set/is_not_set on firstName/lastName only (the other two always have a value). - status — equals, not_equals, in, not_in over ENABLED, DISABLED, BLOCKLISTED. - score — equals, not_equals, greater_than, less_than, greater_than_or_equals, less_than_or_equals, in, not_in; numbers only. - tags — contains/not_contains (one tag), equals/not_equals (all of), in/not_in (any of), is_set/is_not_set. - lists — in/not_in over list ids, meaning a CONFIRMED subscription to any of them. Every id must be a list in your team. - subscription_status — equals over UNCONFIRMED, CONFIRMED, UNSUBSCRIBED. - createdAt, updatedAt, lastContactedAt — equals (whole day), before, after, between; ISO 8601 date strings. - lastOpenedAt, lastClickedAt — before/after (newsletter open/click activity relative to a date). - customFields.<path> or attributes.<path> — equals, not_equals, contains, is_set, is_not_set on a key inside the subscriber's custom-field JSON. Paths are not checked against a catalog (the keys are your own); a path no subscriber carries simply matches no one.

Counts of opens, clicks and bounces (opens_count and friends) are deliberately NOT accepted: the API cannot evaluate them, so a segment saved with one could not be counted by GET /segments/{segmentId}/count. Create those in the dashboard.

Everything this endpoint accepts is guaranteed evaluatable by the count endpoint. The stored definition is not echoed back and is not published on segment reads.

Merge-patch at the field level: omit a field to leave it alone. conditions is REPLACED wholesale, never merged — send the complete definition you want, in the same language POST /segments accepts. Neither field is nullable, so null is a 400.

Campaigns that target this segment pick up the new definition on their next send: the audience is evaluated at send time, not saved when the campaign is.

Permanent, and there is no undo — call with ?dry_run=true first.

A segment is a saved filter: deleting it touches no subscriber, and nothing else in the database references it, so nothing cascades and nothing is detached. The one thing to check first is newsletter campaigns — a campaign that targets this segment keeps its id in the campaign's settings, and a send whose targeting names a segment that no longer exists deliberately delivers to NOBODY (it fails closed rather than widening to the whole list). A scheduled campaign pointed at this segment will therefore go out empty. Retarget those campaigns before deleting.

Evaluates the segment against the current subscriber set and returns the number of matches. Every matching subscriber is counted whatever their status; save a segment with a status condition if you want a narrower number.

This is a live aggregate over the subscriber table, not a stored value, so it is slower than an ordinary read. Cache the result rather than polling it.

Segments that filter on newsletter opens, clicks or bounces cannot be evaluated here and return 400 filter_unsupported: those records are not part of the public API, and returning a number computed without them would be silently wrong.