Segment conditions
A segment narrows one audience to the contacts that match its conditions, minus the members of the segments it excludes. It is evaluated when a broadcast starts (and when a preview counts it), so a contact who changes after the segment was saved is judged by their current data. The conditions are a small tree, sent as JSON with POST /v1/segments (broadcasts.createSegment) and changed with PATCH /v1/segments/{segment_id} (broadcasts.updateSegment).
The tree
{
"all": [
{ "field": "plan", "op": "in", "value": ["pro", "business"] },
{ "field": "consent.source", "op": "eq", "value": "product updates" },
{
"any": [
{ "field": "engagement.last_clicked_at", "op": "within_days", "value": 90 },
{ "field": "engagement.campaigns_30d", "op": "lt", "value": 2 }
]
}
],
"exclude": ["seg_01h455vb4pex5vsknk084sn05x"]
}- The root holds
all(every child matches),any(at least one child matches) or both, and an optionalexclude. When the root has both, a contact must satisfy both lists. - A child is a condition
{ field, op, value }or a group{ all },{ any }or both. Groups nest 3 levels deep (the root is level 1, and level 3 holds conditions only). - At most 20 conditions in the whole tree, and a group lists at least one child.
excludenames at most 8 other segments of the tenant (never the segment itself); their matches are removed from this segment's.
Fields
A field is either one of six fixed fields that broadcasts keeps for every contact, or a contact field of the tenant (the fields an import or the API wrote). A contact field is a path of 1 to 4 lower-case parts separated by dots (plan, address.city), at most 64 characters; the first part may not be engagement, consent or status, which belong to the fixed fields.
| Field | Kind | What it holds |
|---|---|---|
engagement.last_delivered_at | timestamp | the last delivery of a campaign to the contact |
engagement.last_clicked_at | timestamp | the last click in a campaign |
engagement.campaigns_30d | count | campaigns accepted for the contact in the last 30 days |
consent.source | label | the consent source of the contact's import |
consent.collected_at | timestamp | when that consent was collected |
status | status | active, unsubscribed, bounced or complained |
Operators
| Operator | Value | Matches |
|---|---|---|
eq | one value | the field equals the value |
ne | one value | the field does not equal the value; a contact without the field matches |
in | a list of 1 to 50 values | the field equals one of them |
contains | a non-empty string | the field contains the text, ignoring case |
gt | a number; an instant for a timestamp; a string on a contact field | the field is greater (later; as text for a string) |
lt | a number; an instant for a timestamp; a string on a contact field | the field is smaller (earlier; as text for a string) |
exists | none | the field is set |
within_days | a whole number from 1 to 3650 | the timestamp lies within that many days before the evaluation |
Each kind of field admits its own operators:
| Kind | Operators |
|---|---|
| timestamp | exists, within_days, gt, lt |
| count | eq, ne, in, gt, lt |
| label | eq, ne, in, contains, exists |
| status | eq, ne, in |
| contact field | eq, ne, in, contains, gt, lt, exists |
Values are typed. A contact field matches only a value of the same JSON type: { "op": "eq", "value": 3 } finds contacts whose field is the number 3, not the text "3". An import writes every cell as text, so compare imported fields with strings; a gt or lt with a string compares as text ("10" sorts before "9"), and one with a number never matches a text field. A string value has at most 256 characters; in takes strings or numbers, never booleans; a count takes whole numbers (zero or more for eq, ne and in).
Refusals name paths, never values. A tree whose shape or bounds the request schema refuses (an unknown operator, a field name outside the pattern, too deep, too many conditions) answers 400 with the validation problem and the path of every issue, dot-joined (conditions.all.1.value). A tree that passes the schema but uses a reserved field name, a path of more than 4 parts, or an operator or value the field does not admit answers 422 with the path of the first offending node (conditions.all[1].value). A preview whose count runs past its 5-second bound answers 422 on conditions: narrow the conditions.
Previews and changes
POST /v1/segments/{segment_id}/preview(broadcasts.previewSegment) counts the matching contacts of the audience, with suppressed contacts already left out, up to 100,000 (count_is_lower_boundis true above it), and answers up to 20 contact ids as a sample. It shares thepreviewrate class (10 a minute) and its count is kept for 5 minutes.- A segment that an approved, scheduled or running broadcast uses cannot change its conditions (
409withsegment.in_use): the approval covered what the broadcast would reach. Renaming it is always allowed; to change the conditions, cancel or edit the broadcast first (an edit clears its approval).