Email.com docsOpen the app

Guides

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"]
}

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.

FieldKindWhat it holds
engagement.last_delivered_attimestampthe last delivery of a campaign to the contact
engagement.last_clicked_attimestampthe last click in a campaign
engagement.campaigns_30dcountcampaigns accepted for the contact in the last 30 days
consent.sourcelabelthe consent source of the contact's import
consent.collected_attimestampwhen that consent was collected
statusstatusactive, unsubscribed, bounced or complained

Operators

OperatorValueMatches
eqone valuethe field equals the value
neone valuethe field does not equal the value; a contact without the field matches
ina list of 1 to 50 valuesthe field equals one of them
containsa non-empty stringthe field contains the text, ignoring case
gta number; an instant for a timestamp; a string on a contact fieldthe field is greater (later; as text for a string)
lta number; an instant for a timestamp; a string on a contact fieldthe field is smaller (earlier; as text for a string)
existsnonethe field is set
within_daysa whole number from 1 to 3650the timestamp lies within that many days before the evaluation

Each kind of field admits its own operators:

KindOperators
timestampexists, within_days, gt, lt
counteq, ne, in, gt, lt
labeleq, ne, in, contains, exists
statuseq, ne, in
contact fieldeq, 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