Segments

A segment is everyone matching its filter, plus the contacts you add by hand.

Membership is recomputed every time you read it. A contact that gains a matching property joins immediately. There is no scheduled rebuild that can fall behind.

A segment whose filter has no conditions holds only its hand-added members, which is how you keep a fixed list.

Filter shape

A filter is a tree of groups and conditions:

json

{
  "all": [
    { "field": "unsubscribed", "op": "eq", "value": false },
    { "any": [
      { "field": "property:plan", "op": "eq", "value": "pro" },
      { "field": "email", "op": "ends_with", "value": "@acme.com" }
    ]}
  ]
}

The operator key is op, not operator.

all is AND, any is OR, and they nest.

Empty groups

Inside a filter that has conditions, an empty all matches everyone and an empty any matches no one. A filter with no conditions at all matches nobody, so only hand-added members are in the segment.

Fields

Field	Operators
`email`	`eq` `ne` `contains` `starts_with` `ends_with`
`unsubscribed`	`eq` (with `true` / `false`), for the opt-out from all email
`property:<key>`	Depends on the declared type — see the full table.

set and not_set ask whether the key is present and take no value.

A property: field must name a declared property definition; an undeclared key is refused, because the declaration is what says which operators are legal.

Reading the members

bash

curl "http://api.localhost/v1/segments/$SEGMENT_ID/contacts?page=1&per_page=100" \
  -H "X-API-Key: $NOTIFYZR_API_KEY"

Because membership is live, two calls a minute apart can legitimately return different totals.

Adding members by hand

bash

curl -X POST "http://api.localhost/v1/segments/$SEGMENT_ID/members" \
  -H "X-API-Key: $NOTIFYZR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": ["3f2504e0-4f89-41d3-9a0c-0305e82c3301"]}'

You can also set a contact's hand-added segments with segment_ids when you create or update it. See the API reference.

Opting out of a segment

Recipients can opt out of a single segment on the preference page. That stops broadcasts to that segment only. Switch on Show on the preference page and set a public name to let members see the segment there.

Deleting

Deleting a segment removes the definition, its hand-added members and its opt-outs. No contact is touched. A segment that a broadcast references cannot be deleted while that broadcast exists.

Segments ​

Filter shape ​

Fields ​

Reading the members ​

Adding members by hand ​

Opting out of a segment ​

Deleting ​