Skip to main content
Segments are explicit groups of contacts that you can use when targeting bulk messaging. They are intentionally simple: a contact either belongs to a segment or it does not.

​
When to use segments

Use segments for audience selection such as:
  • customers on a specific plan,
  • users in a lifecycle stage,
  • attendees for an event,
  • recipients selected by an internal workflow.
Segments describe who you want to target. They do not describe whether the contact is allowed or willing to receive a particular category of message.

​
Membership and preferences are separate

A contact can belong to a segment while being opted out of a topic, globally unsubscribed from email, or suppressed. That separation lets your application keep business targeting independent from messaging eligibility.

​
Segment membership

Contacts can belong to multiple segments at the same time. Membership is explicit and can be added or removed without changing the contact profile itself. For endpoint details for creating segments or managing contact membership, see the Segments and Contacts sections in the API Reference.

​
Audience size

Use the dedicated audience-size endpoint when you only need the current number of contacts assigned to a segment:
A successful response returns the segment ID and membership count:
The count represents segment membership, not final delivery eligibility. A member may still be globally unsubscribed, opted out of a topic, or suppressed when a broadcast is prepared.
Use GET /segments/{segment_id}/audience-size when you only need the size. You do not need to page through the segment’s contacts and count them yourself.

​
List segments with limit and offset

GET /segments uses limit and offset pagination:
The pagination rules are:
  • omitted or non-positive limit uses 50,
  • limit values above 100 are capped at 100,
  • omitted or negative offset uses 0,
  • malformed numeric values such as limit=abc return a bad-request error.
The response data is an array of segments. There is no cursor or has_more field for this endpoint.

​
List contacts in a segment

GET /segments/{segment_id}/contacts uses the same limit and offset rules:
Each returned contact includes its contact ID, team ID, email, optional first and last name, global email unsubscribe state, and timestamps. To read the full membership set, continue increasing offset by the number of contacts returned until a page contains fewer contacts than the effective limit.