Segments
Group contacts dynamically with rule-based membership and logical operators.
Segments are dynamic groups of contacts defined by rules. Unlike static lists, segment membership is computed based on contact properties, engagement data, and even membership in other segments. When a contact's data changes, their segment membership is re-evaluated.
Creating a segment
Create a segment by providing a name and a set of rules:
const segment = await kraiter.segments.create({
name: 'active-pro-users',
rules: {
operator: 'and',
conditions: [
{
type: 'property',
field: 'properties.plan',
operator: 'equals',
value: 'pro',
},
{
type: 'property',
field: 'properties.lastLoginDate',
operator: 'greaterThan',
value: '2025-01-01',
},
],
},
});curl -X POST https://api.kraiter.com/api/segments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "active-pro-users",
"rules": {
"operator": "and",
"conditions": [
{
"type": "property",
"field": "properties.plan",
"operator": "equals",
"value": "pro"
},
{
"type": "property",
"field": "properties.lastLoginDate",
"operator": "greaterThan",
"value": "2025-01-01"
}
]
}
}'Rules and operators
Condition operators
Each condition has a type (property, derived, or segment). Property and derived conditions compare a field against a value using an operator:
| Operator | Applicable types | Description |
|---|---|---|
equals | string, number, boolean, date | Exact match |
notEquals | string, number, boolean, date | Not equal |
greaterThan | number, date | Greater than value |
lessThan | number, date | Less than value |
greaterOrEqual | number, date | Greater than or equal to |
lessOrEqual | number, date | Less than or equal to |
contains | string | String contains substring |
notContains | string | String does not contain substring |
startsWith | string | String starts with value |
endsWith | string | String ends with value |
includes | array | Array includes the value |
notIncludes | array | Array does not include the value |
includesAll | array | Array includes all of the given values |
includesAny | array | Array includes any of the given values |
exists | all | Property has a non-null value |
notExists | all | Property is null or absent |
Combining rules with AND/OR
Rules support three logical operators: and, or, and not.
AND — All conditions must be true:
{
operator: 'and',
conditions: [
{ type: 'property', field: 'properties.plan', operator: 'equals', value: 'pro' },
{ type: 'property', field: 'properties.isVip', operator: 'equals', value: true },
],
}OR — At least one condition must be true:
{
operator: 'or',
conditions: [
{ type: 'property', field: 'properties.plan', operator: 'equals', value: 'pro' },
{ type: 'property', field: 'properties.plan', operator: 'equals', value: 'enterprise' },
],
}NOT — Negates its conditions (true when they do not match).
Nesting rules
You can nest rule groups to build complex logic:
{
operator: 'and',
conditions: [
{
type: 'property',
field: 'properties.country',
operator: 'equals',
value: 'GB',
},
{
operator: 'or',
conditions: [
{ type: 'property', field: 'properties.plan', operator: 'equals', value: 'pro' },
{ type: 'property', field: 'properties.plan', operator: 'equals', value: 'enterprise' },
],
},
],
}This segment matches contacts in the UK who are on either the Pro or Enterprise plan.
Segment dependencies
A segment can use membership in another segment as a condition. This lets you build layered audience definitions.
const segment = await kraiter.segments.create({
name: 'vip-in-trial',
rules: {
operator: 'and',
conditions: [
{
type: 'segment',
segmentId: 'high-value-customers',
operator: 'memberOf',
},
{
type: 'property',
field: 'properties.plan',
operator: 'equals',
value: 'trial',
},
],
},
});The memberOf operator checks whether the contact is a member of the referenced segment. You can also use notMemberOf to exclude members of another segment.
Be careful not to create circular dependencies — segment A depending on segment B which depends on segment A. Kraiter will reject such configurations.
Membership computation
Segment membership is not evaluated in real time. Instead, membership is computed in two ways:
Manual trigger
You can trigger a membership computation via the API:
await kraiter.segments.compute('active-pro-users');This starts a background job that evaluates every contact against the segment's rules and updates the membership list.
Background computation
Kraiter periodically recomputes segment membership in the background. The exact frequency depends on your tenant configuration, but it typically runs at regular intervals.
Safety: fail = not a member
When evaluating segment membership, if a rule evaluation fails for any reason (missing property, data type mismatch, computation error), the contact is considered not a member of the segment. This is a deliberate safety measure — it is better to exclude a contact from a segment than to incorrectly include them and send an unwanted email.
Listing segment members
Retrieve the current members of a segment:
const { items, nextCursor } = await kraiter.segments.listMembers('active-pro-users', {
limit: 100,
});curl "https://api.kraiter.com/api/segments/active-pro-users/members?limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"Updating a segment
Update the rules of an existing segment:
await kraiter.segments.update('active-pro-users', {
rules: {
operator: 'and',
conditions: [
{ type: 'property', field: 'properties.plan', operator: 'equals', value: 'pro' },
{ type: 'property', field: 'properties.lastLoginDate', operator: 'greaterThan', value: '2025-06-01' },
],
},
});After updating the rules, trigger a recomputation to refresh the membership list:
await kraiter.segments.compute('active-pro-users');Using segments in sequences
Segments can be used in sequence conditions to control the flow:
steps:
- action: condition
segment: high-value-customers
onTrue: skip
- action: email
template: upgrade-promptThis skips the upgrade prompt for contacts who are already high-value customers.