Segments
Dynamic and static segments, the condition AST (all/any/none), field and operator list, behavior and location conditions, preview/estimate endpoints and campaign usage.
A segment is a saved condition tree that selects users (and their subscriptions). Dynamic segments are recomputed on every send; static segments are frozen with POST …/segments/{id}/refresh or via import. The same condition language is used in target.filters inside POST /v1/notifications, in POST …/users/search, and in in-app/journey audiences.
Condition language
{
"all": [
{ "field": "tag", "name": "plan", "op": "eq", "value": "pro" },
{ "field": "last_active_at", "op": "within_days", "days": 30 },
{ "any": [
{ "field": "event", "name": "purchase", "op": "count_gte", "value": 3, "days": 90 },
{ "field": "property", "name": "ltv", "op": "gt", "value": 500 }
] },
{ "none": [ { "field": "message", "event": "opened", "op": "has", "within_days": 7 } ] }
]
}Groups: all (AND), any (OR), none (NOT); they can be nested (at most 50 conditions per group; the compiler limits depth). Each condition carries field, op and, where needed, name/value/days.
Fields
field | Description | Extra keys |
|---|---|---|
tag | User tag | name |
property | Typed property (numeric comparison) | name |
language, country, timezone | Subscription/user metadata | — |
device_type, device_os, app_version | Device; app_version compares semver | — |
channel, subscription_status | Subscription channel/status | — |
first_session_at, last_active_at, created_at | Time fields | days |
session_count, usage_duration | Session count / total duration | — |
event | Event count (user_event_counts) | name, days, where ({ key, value } property filter) |
message | Message behavior: sent, delivered, failed, bounced, opened, clicked | event, within_days, message_id, campaign_id, journey_id, channel |
in_app | In-app behavior: impression, clicked, dismissed | event, within_days, in_app_message_id |
segment | Membership in another segment | value (segment id) |
location | Within a radius (location) | lat, lng, radius_km, days |
Operators
| Group | Operators |
|---|---|
| Comparison | eq, neq, exists, not_exists, contains, starts_with, gt, lt, gte, lte, in, not_in, between |
| Time | within_days (within the last N days), before_days (older than N days) |
| Version | semver_gte, semver_lt (app_version) |
| Event count | count_gte, count_lte, not_performed (event) |
| Behavior | has, has_not (message, in_app) |
| Location | within_radius (location) |
Field × operator validity is checked by the compiler; an incompatible combination returns 400 HS_VALIDATION_ERROR. Schema: API → schemas.
API
| Operation | Endpoint | Scope |
|---|---|---|
| List | GET /v1/apps/{app_id}/segments?q=&cursor= | segments:read |
| Create / update / delete | POST, PATCH …/{id}, DELETE …/{id} (a segment in use returns 409) | admin |
| Preview (without saving) | POST …/segments/preview { definition } → count + sample users | segments:read |
| Estimate | POST …/segments/{id}/estimate → cached count (channel breakdown) | segments:read |
| Static refresh | POST …/segments/{id}/refresh | admin |
| Campaigns using it | GET …/segments/{id}/campaigns | segments:read |
Examples: API → Segments. Use included_segments / excluded_segments in campaigns and notifications; segment counts are shown per channel for the email/SMS channels.
Performance and behavior
- Conditions are compiled to parameterized SQL; event counts are read from the
user_event_countstable (user × event × day), with no raw event scans. - Estimates are cached briefly (dashboard counter); the exact audience is computed at send time and returned as
recipients_estimate. - Segment conditions do not look at subscription status; at send time, only
activesubscriptions are used and channel/preference/suppression filters are applied. - The dashboard's Audience → Segments shows the visual builder, live count and campaign usage; on the Users page, the same builder applies ad-hoc filters.
Users, aliases and subscriptions
The Pushizo identity model — end users, external_id and custom aliases, subscriptions (device, email, phone), tags/properties/deltas, anonymous → identified merging, events and public API endpoints.
SQL query and SQL segment
Define your audience with SQL when the rule builder is not enough: run a read-only SELECT query on the permitted views, see the result in a table and save the people in the result as a segment. A SQL segment is…