Segments

Organize contacts into segments for targeted broadcasts. Segments can be manual (explicitly add/remove contacts) or dynamic (auto-populated based on filter rules).

POST

/segments

Create a new segment. Omit rules for a manual segment, or provide rules for a dynamic segment that auto-populates based on conditions.

json

{
  "name": "Pro Users",
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "field": "plan",
        "comparator": "equals",
        "value": "pro"
      },
      {
        "field": "unsubscribed",
        "comparator": "equals",
        "value": "false"
      }
    ]
  }
}

GET

/segments

List all segments with contact counts.

json

{
  "segments": [
    {
      "id": "seg_abc123def456ghi789",
      "name": "Pro Users",
      "contact_count": 342,
      "created_at": "2026-03-23T10:00:00.000Z"
    },
    {
      "id": "seg_jkl012mno345pqr678",
      "name": "Beta Testers",
      "contact_count": 58,
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ]
}

GET

/segments/:id

Retrieve a single segment with its rules (if dynamic) and contact count.

json

{
  "id": "seg_abc123def456ghi789",
  "name": "Pro Users",
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "field": "plan",
        "comparator": "equals",
        "value": "pro"
      }
    ]
  },
  "contact_count": 342,
  "created_at": "2026-03-23T10:00:00.000Z",
  "updated_at": "2026-03-23T12:00:00.000Z"
}

PATCH

/segments/:id

Update a segment's name and/or rules. Set rules to null to convert a dynamic segment to manual.

json

{
  "name": "Active Pro Users",
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "field": "plan",
        "comparator": "equals",
        "value": "pro"
      },
      {
        "field": "email",
        "comparator": "contains",
        "value": "@company.com"
      }
    ]
  }
}

POST

/segments/preview

Preview which contacts match a set of rules without creating or modifying a segment. Useful for testing rules before saving.

json

{
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "field": "plan",
        "comparator": "equals",
        "value": "pro"
      }
    ]
  }
}

POST

/segments/:id/contacts

Add contacts to a manual segment. Provide an array of contact IDs (up to 1,000 per request).

json

{
  "contact_ids": [
    "ct_abc123def456ghi789",
    "ct_jkl012mno345pqr678"
  ]
}

DELETE

/segments/:id/contacts/:contactId

Remove a single contact from a manual segment.

json

{
  "success": true
}

DELETE

/segments/:id

Delete a segment. Contacts in the segment are not deleted.

json

{
  "deleted": true
}

Dynamic Segment Rules

Dynamic segments auto-populate based on filter rules. Rules consist of an operator (and or or) and an array of conditions. Each condition has a field, comparator, and value:

json

{
  "rules": {
    "operator": "and",
    "conditions": [
      { "field": "plan", "comparator": "equals", "value": "pro" },
      { "field": "email", "comparator": "contains", "value": "@company.com" }
    ]
  }
}

Comparators

Comparator	Description
`equals`	Exact match on the field value
`not_equals`	Field value does not match
`contains`	Field value contains the substring
`starts_with`	Field value starts with the string
`ends_with`	Field value ends with the string

Available Fields

Conditions can target built-in contact fields or any custom contact property name:

Field	Description
`email`	Contact email address
`firstName`	Contact first name
`lastName`	Contact last name
`unsubscribed`	Subscription status (true/false)
Custom property names	Any custom contact property (e.g. `plan`, `company`)