Segments

A segment is a named, dynamically-defined group of contacts that you can target with a campaign.

Overview

When you create or update a campaign, you choose a segment as its audience by setting segment_uuid to a segment's UUID. This endpoint group lets you create a segment, list the segments on your account, look one up, and page the contacts who currently match it.

Endpoints

Method	Endpoint	Description
POST	/segments	Create a segment
GET	/segments	List segments
GET	/segments/{uuid}	Get a specific segment
GET	/segments/{uuid}/contacts	List contacts in a segment

Segment Object

Field	Type	Description
uuid	string	Unique identifier for the segment. Use it as a campaign's segment_uuid.
name	string|null	Segment name. null when the segment has no name.
contacts_count	integer	Number of contacts in the segment. See Audience size.
contacts_count_calculated_at	string|null	ISO 8601 timestamp (UTC) of when contacts_count was last calculated, or null when it has never been calculated.
filters	object|null	The segment's filter tree. null when the segment has none, or when its stored filters are no longer valid. See Filters.
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

List Segments omits filters.

Audience size

contacts_count is the segment's audience size. It is a cached figure refreshed periodically, so it can be a few minutes out of date and is best treated as approximate. contacts_count_calculated_at is the timestamp of the last calculation; it is null until the count has been calculated for the first time, in which case contacts_count is 0.

List Segment Contacts pages the contacts who match right now. pagination.total on that response can differ from contacts_count.

Filters

filters is the rule that decides which contacts belong to the segment. Get Segment and Create Segment return it in the same shape. Get Segment returns the tree as stored, including a custom field that has since been deleted. Create Segment rejects that key.

A segment with no filters matches every contact who can receive mail, as does a root group whose conditions array is empty.

Keys inside the tree are camelCase (fieldKey, modelId, withinDays).

A tree holds at most 50 conditions, counted across every group. More is The filters may contain at most 50 conditions. A tree holds at most 50 groups, including the root group. More is The filters may contain at most 50 groups, including the root group. Groups nest at most 3 levels deep, counting the root group as the first level. Deeper nesting is Filter groups may be nested at most 3 levels deep.

Field	Type	Description
root	object	The root group. See Filter group.

Filter group

Field	Type	Description
type	string	group
operator	string	AND or OR. How the group's children are combined.
conditions	array	Nested groups and conditions. An empty array adds no constraint. A group without a conditions array is A filter group is missing its conditions. or A filter group's conditions must be an array. Each item's type is group or condition; any other is Unknown filter node type '<type>'.

Filter condition

Field	Type	Description
type	string	condition
fieldKey	string	A built-in field from the sections below, or a custom field key on the account. A key that is neither is Unknown filter field '<key>'.
operator	string	An operator the field allows. An unknown operator is Invalid operator '<operator>' for field '<key>'. An operator the field does not allow is Operator '<operator>' is not allowed for field '<key>'.
value	string|number|boolean|null	The comparison value, or the UUID of a list, campaign, or automation on the account when the field requires one. That UUID is stored and returned in lowercase. null when the condition has none. A missing or empty UUID on a field that requires one is Field '<key>' requires a value. An array or object is The value for field '<key>' must be a string, number, boolean, or null.
kind	string	property, custom_field, campaign_activity, list_membership, or automation_activity, matching the field. An unknown kind is Invalid filter kind '<kind>' for field '<key>'. A kind that does not match the field is Filter kind '<kind>' does not match field '<key>'.
modelId	string|null	The instance of a custom field to match. See Custom fields and One-time product. null when the condition does not set it. A UUID is stored and returned in lowercase. A value that is not a string is The modelId for field '<key>' must be a string or null.
withinDays	integer|null	A positive number of days, at most 3650, or null for no time window. More than 3650 is The withinDays for field '<key>' must be at most 3650. Accepted on campaign activity and automation activity. A positive integer on any other field is Field '<key>' does not support a time window. A value that is not an integer is The withinDays for field '<key>' must be an integer or null. Zero or a negative integer comes back as null.

With every operator except exists, not_exists, is_empty, and is_not_empty, value is required. A missing value, null, "", or a string of only whitespace is The value for field '<key>' is required for operator '<operator>'. Use is_empty or is_not_empty to match on whether a field has a value.

A required value must also have the type listed for its field in the sections below. Otherwise it is rejected, by field type:

Field type	Message
Boolean custom field	The value for field '<key>' must be a boolean.
Number custom field	The value for field '<key>' must be a number.
Date or datetime custom field	The value for field '<key>' must be a date string.
Text, select, or list custom field, or a contact property	The value for field '<key>' must be a string.

Contact properties

kind is property.

fieldKey	Operators	value
email, first_name, last_name, phone	equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty	The string to compare, or an integer.
language, country_code	equals, not_equals, is_empty, is_not_empty	A language or country code, as a string.

Campaign activity

kind is campaign_activity. operator is exists or not_exists. withinDays may be a positive integer.

fieldKey	value
any_email_opened, any_email_clicked	Not used.
campaign_sent, campaign_opened, campaign_clicked	Required. The UUID of a campaign on the account. Any other value is Unknown campaign '<value>' for field '<key>'.

not_exists on any_email_opened matches contacts who were sent at least one email and did not open it. not_exists on any_email_clicked matches contacts who were sent at least one email and did not click it. not_exists on campaign_opened matches contacts who were sent that campaign and did not open it. not_exists on campaign_clicked matches contacts who were sent that campaign and did not click it.

exists on campaign_sent matches contacts who were sent that campaign. not_exists matches contacts who were not.

List membership

contact_list uses kind list_membership and operator exists or not_exists. value is the UUID of a list on the account and is required. Any other value is Unknown contact list '<value>' for field 'contact_list'.

exists matches contacts on that list. not_exists matches contacts who are not.

Automation activity

automation_running and automation_completed use kind automation_activity and operator exists or not_exists. value is the UUID of an automation on the account and is required. Any other value is Unknown automation '<value>' for field '<key>'. withinDays may be a positive integer.

exists on automation_running matches contacts with a run still in progress. exists on automation_completed matches contacts with a finished run. not_exists matches contacts without that run.

Custom fields

Any other fieldKey is a custom field on the account, including a field created with Custom Fields. kind is custom_field. When the account has no such field, create rejects the key — see Filter condition.

Operators and value follow the field's type:

Type	Operators	value
text	equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty	The string to compare, or an integer.
number	equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, is_empty, is_not_empty	A number, or a numeric string.
date, datetime	equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, is_empty, is_not_empty	A date string, or last7days, last14days, last30days, last3months, or last12months. Any other non-empty string is Invalid date value '<value>' for field '<key>'.
boolean	equals, not_equals	true or false, as a JSON boolean.
select	equals, not_equals, is_empty, is_not_empty	One of the field's options.
list	equals, not_equals, contains, not_contains, is_empty, is_not_empty	A string or an integer. equals matches when one element equals that string, ignoring case. contains matches when an element contains it as a substring, ignoring case.

A custom field that only records whether a value is present uses exists and not_exists, and value is not used. as:one_time_product is one of these — see One-time product. as:subscription_for_product is another. It is available once the account has a subscription for a product. Until then, create returns Unknown filter field 'as:subscription_for_product'.

modelId is optional on every custom field except one-time product, and does not apply to a list field. Omit it, or send null, to match any instance of the field.

One-time product

as:one_time_product is not present on every account. It is available once the account has a one-time product purchase. When the account does not have the field, Create Segment returns 422 and details.filters includes Unknown filter field 'as:one_time_product'.

kind is custom_field and operator is exists or not_exists. modelId is the product's UUID and is required. A missing or non-UUID modelId is Field 'as:one_time_product' requires a UUID modelId. value is not used. exists matches contacts who purchased that product. not_exists matches contacts who did not.