Segments

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:

SDK

const segment = await kraiter.segments.create({
  name: 'active-pro-users',
  rules: {
    operator: 'and',
    conditions: [
      {
        property: 'contact.properties.plan',
        operator: 'equals',
        value: 'pro',
      },
      {
        property: 'contact.properties.lastLoginDate',
        operator: 'greaterThan',
        value: '2025-01-01',
      },
    ],
  },
});

cURL

curl -X POST https://api.kraiter.com/segments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "active-pro-users",
    "rules": {
      "operator": "and",
      "conditions": [
        {
          "property": "contact.properties.plan",
          "operator": "equals",
          "value": "pro"
        },
        {
          "property": "contact.properties.lastLoginDate",
          "operator": "greaterThan",
          "value": "2025-01-01"
        }
      ]
    }
  }'

Rules and operators

Condition operators

Each condition compares a contact property against a value using an operator:

Operator	Applicable types	Description
`equals`	string, number, boolean, date	Exact match
`notEquals`	string, number, boolean, date	Not equal
`contains`	string	String contains substring (case-insensitive)
`notContains`	string	String does not contain substring
`greaterThan`	number, date	Greater than value
`lessThan`	number, date	Less than value
`greaterThanOrEquals`	number, date	Greater than or equal to
`lessThanOrEquals`	number, date	Less than or equal to
`exists`	all	Property has a non-null value
`notExists`	all	Property is null or absent

Combining rules with AND/OR

Rules support two logical operators: and and or.

AND — All conditions must be true:

SDK

{
  operator: 'and',
  conditions: [
    { property: 'contact.properties.plan', operator: 'equals', value: 'pro' },
    { property: 'contact.properties.isVip', operator: 'equals', value: true },
  ],
}

OR — At least one condition must be true:

SDK

{
  operator: 'or',
  conditions: [
    { property: 'contact.properties.plan', operator: 'equals', value: 'pro' },
    { property: 'contact.properties.plan', operator: 'equals', value: 'enterprise' },
  ],
}

Nesting rules

You can nest rule groups to build complex logic:

SDK

{
  operator: 'and',
  conditions: [
    {
      property: 'contact.properties.country',
      operator: 'equals',
      value: 'GB',
    },
    {
      operator: 'or',
      conditions: [
        { property: 'contact.properties.plan', operator: 'equals', value: 'pro' },
        { property: 'contact.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.

SDK

const segment = await kraiter.segments.create({
  name: 'vip-in-trial',
  rules: {
    operator: 'and',
    conditions: [
      {
        segment: 'high-value-customers',
        operator: 'memberOf',
      },
      {
        property: 'contact.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:

SDK

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:

SDK

const { items, nextCursor } = await kraiter.segments.members('active-pro-users', {
  limit: 100,
});

cURL

curl "https://api.kraiter.com/segments/active-pro-users/members?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Updating a segment

Update the rules of an existing segment:

SDK

await kraiter.segments.update('active-pro-users', {
  rules: {
    operator: 'and',
    conditions: [
      { property: 'contact.properties.plan', operator: 'equals', value: 'pro' },
      { property: 'contact.properties.lastLoginDate', operator: 'greaterThan', value: '2025-06-01' },
    ],
  },
});

After updating the rules, trigger a recomputation to refresh the membership list:

SDK

await kraiter.segments.compute('active-pro-users');

Using segments in sequences

Segments can be used in sequence conditions to control the flow:

Sequence YAML

steps:
  - action: condition
    segment: high-value-customers
    onTrue: skip
  - action: email
    template: upgrade-prompt

This skips the upgrade prompt for contacts who are already high-value customers.

Segments

On this page