Use segments to identify and target a subset of your contacts that meet your specified criteria.
What is Segmentation?
Segmentation is a marketing strategy used to increase campaign engagement and improve campaign results by targeting the right contacts, at the right time, with the right campaign.
Using the Constant Contact user interface (UI) or the V3 API, you create segments that Constant Contact uses to evaluate and identify a resulting subset of contacts meeting your specified segment criteria.
You specify contact-related data as segment criteria from the following data sources:
-
Tracking activities (
tracking
): Constant Contact tracks how a contact interacts with your past campaigns. To include contacts based on contact tracked activities, specify thetracking
activities to use in the segment criteria. For example, you can choose to include contacts that opened and clicked an email campaign activity within the last 60 days. -
Contact details (
contact
): To include or exclude contacts based on contact details and custom contact fields, specify thecontact
data to use in the segment criteria. For example, you can create a segment that includes contacts that have birthdays in April, and that do not live in Maryland. -
List memberships (contact
list_membership
): To limit the number of contacts Constant Contact evaluates, specify the contact list(s) to use. If no contact list is specified, all contacts in your account are evaluated. -
Tags (
tags
): To include or exclude contacts based on tags, specify the tags (bytag_id
) to use in the segment criteria.
The following shows segment criteria and data source examples.

After creating and saving a segment, review the segment’s contact results. To correct or refine the results, update the segment criteria. When you are ready, use the segment to target contacts for the intended campaign.
Unlike contact lists, segments are dynamic. A segment’s contact results can differ over time based on changes to contact interaction with campaigns (tracked activities), contact details, and contact list assignment.
[CLICK] Example: Use Case
In January, you create a new "Engage Inactive Users" campaign that uses your existing "Non-Openers-US" segment to identify inactive contacts living in the United States. The segment criteria specifies the `tracking` and `contact` data used to get contacts that were sent but did not open any of your last five campaigns, and that live in the United States. As a result, 1500 targeted contacts are sent the campaign. In March, you decide to create a new campaign that includes additional enticements, such as free shipping, and that uses the same segment. As a result, only 500 targeted contacts are identified. The segment criteria did not change, so what did change? Since sending the "Engage Inactive Users" campaign in January, 1000 contacts opened at least one of your last five campaigns, or they were excluded from the results because they moved to another country.TIP: | To help determine your segmentation strategy, you can use V3 reporting endpoints to gain insights about your past email campaigns. |
Learn More about using email reports that track how contacts interact with your email campaigns.
Learn More about how a specific contact interacts with your email campaigns.
Segment Criteria
You can create a segment using either the Constant Contact user interface or using the V3 API POST /segments
endpoint. Both require that you specify a segment name
and the segment_criteria
to use.
For readability purposes, many of the JSON examples in this topic are not formatted to use single-string escaped JSON (required).
TIP: | Use a text formatter or editor of your choice, such as the JSON Formatter, to remove white spaces, extra lines, and to replace ” with \” in the segment_criteria . |
[CLICK] Example: Create Segment Using the UI
The following Constant Contact Create Segments screen shows how the UI represents the data sources from which you can select segment criteria. You group segment criteria from different data sources using "AND".

[CLICK] Example: POST /segments
Request
In the example that follows, the segment_criteria
specifies tracking
as the data source
to use when evaluating contacts that opened ("field": "opened"
) any ("op": "contains-any"
) of the last five campaigns (”const_value": "last-n-campaigns”
and "param": "5"
). The maximum number of campaigns that Constant Contact UI evaluates for tracking data is 5.
{
"name": "Opened last five campaigns",
"criteria":
{
"type": "and",
"group": [
{
"source": "tracking",
"field": "opened",
"op": "contains-any",
"const_value": "last-n-campaigns",
"param": "5"
}
]
}
}
[CLICK] Example: POST /segments
Single-String Escaped JSON Request
{ "name":"Opened last five campaigns",
"segment_criteria":"{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}"
}
[CLICK] Example: POST /segments
Response
The example that follows shows the POST /segments
results. The new segment's details display in the response body. The segment details include the system assigned segment_id
, and the specified name
and segment_criteria
.
{
"name": "Opened last five campaigns",
"segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}",
"segment_id": 16,
"created_at": "2019-12-18T16:30:35.000Z",
"edited_at": "2019-12-18T16:30:35.000Z"
}
When a segment is first created, the created_at
and edited_at
properties have identical timestamps.
Segment Properties
The following table lists and describes segment properties:
Property | Type | Description |
segment_id | integer | The system generated ID that uniquely identifies a segment. |
name | string | The unique name that you specify for a segment. |
created_at | string | The system generated date and time that the segment was created. The read-only date and time displays in ISO-8601 format. For example: 018-02-06T22:09:15.000Z . |
edited_at | string | The system generated date and time that the segment's name or segment_criteria was last edited. The read-only date and time displays in ISO-8601 format. For example: 018-02-06T22:09:15.000Z . |
segment_criteria | string | Specifies the data source and criteria to use to evaluate and filter through your contacts to identify only those contacts that meet your specified criteria. Segment data sources include:
|
Learn More about creating new segments.
Grouping Data Sources
When using the V3 API to group contact data from different data sources, a top-level group must exist in the segment criteria ("segment_criteria\":{\"type\":\"and\",\"group\":
). Under the top group, you add groups from different data sources. For example, you might want to create a segment used to evaluate and identify contacts that are members on a contact list “and” that did not open any of your last five email campaigns. This requires grouping list_membership
data with tracking
data.
Using the V3 API, you group data from different data sources using "type": "and",
.
[CLICK] Example: Grouping Data Sources
{
"version": "1.0.0",
"criteria": {
"type": "and",
"group": [
{
"source": "tracking",
"field": "opened",
"op": "contains-any",
"const_value": "last-n-campaigns",
"param": 5,
"const_date_value": "in-range",
"date_param": [
"2017-12-15T01:16:00+0000",
"2018-02-28T01:16:00+0000"
]
},
{
"type": "or",
"group": [
{
"source": "list_membership",
"field": "list_id",
"op": "eq",
"value": "04fe9a-a579-43c5-bb1a-58ed29bf0a6a"
},
{
"source": "list_membership",
"field": "list_id",
"op": "eq",
"value": "08bd8c-a579-43c5-bb1a-58ed29bf0a6a"
}
]
},
{
"type": "or",
"group": [
{
"source": "contact",
"field": "state",
"op": "eq",
"value": "MA"
},
{
"source": "contact",
"field": "state",
"op": "eq",
"value": "RI"
}
]
},
{
"source": "contact",
"field": "title",
"op": "eq",
"value": "Director"
}
]
}
}
Grouping Rules
When grouping segment criteria from data sources using the V3 API, the following rules apply:
Segment criteria
The segment_criteria
must begin with an and
.
Different data source groups
Must be combined using and
. For example, you cannot use or
to combine tracking
or
contact
groups.
Grouping data from the same data source group
Supports and
and or
for contact
and tracking
data using the following group combinations:
- (
contact
or
contact
)and
contact
- (
contact
or
contact
)and
(contact
or
contact
) - (
tracking
or
tracking
)and
tracking
- (
tracking
or
tracking
)and
(tracking
or
tracking
) - (
list_membership
or
list_membership
or
list_membership
) - (
tags
or
tags
or
tags
)
Does not support:
list_membership
and
list_membership
tags
and
tags
Chaining data from the same data source group
Supports or
when chained with and
, but does not support and
when chained with or
.
- Not supported: (
tracking
and
tracking
)or
tracking
Nesting data
Supports for an or
group when nested within an and
group.
Combining fields from the same data source
Supports combining fields using or
. For example: state eq MA
or
postal_code eq 02451
, as well as intra-fields such as, state eq MA
or
state eq RI
.
Using Operators
Depending on the data source and parameter being specified, the V3 API supports the following operators:
Equals (eq
) - is case-insensitive.
{
"source": "tracking",
"field": "sent",
"op": "eq",
"value": "4c08372c-957a-48b5-bc45-72c7f00796cd"
}
Not Equals (ne
) - is case-insensitive and applies to null
value.
{
"source": "tracking",
"field": "sent",
"op": "ne",
"value": "4c08372c-957a-48b5-bc45-72c7f00796cd"
}
Starts with (starts-with
) - is case-insensitive and applies to string values.
{
"source": "contact",
"field": "title",
"op": "starts-with",
"value": "dir"
}
Contains string (contains-string
) - applies to string values and is case-insensitive.
{
"source": "contact",
"field": "state",
"op": "contains-string",
"value": "Connecticut"
}
Is Blank (eq
blank) - is equal to null
for an empty string or whitespaces in string values.
{
"source": "contact",
"field": "state",
"op": "eq",
"const_value": "blank"
}
Is Not Blank (ne
blank"
) - is not null
, for an empty string or whitespaces in string values.
{
"source": "contact",
"field": "state",
"op": "ne",
"const_value": "blank"
}
Tracking Activities Data Source
Use tracking data as segment criteria to get contacts that engaged or did not engage in specific tracking activities for one or more of your sent email campaigns.
[CLICK] Example: Tracking Segment Criteria Using the UI
The following shows an example of how you can use the UI to specify tracking activities in the segment criteria.

Using the V3 API, specify one or more of the following tracking
activity fields
to use as segment criteria:
Name | Description |
sent |
Contacts that were sent an email campaign activity. |
not_sent |
Contacts that were not sent an email campaign activity. |
opened |
Contacts that opened an email campaign activity. |
not_opened |
Contacts that did not open an email campaign activity. |
clicked |
Contacts that clicked an email campaign activity. |
not_clicked |
Contacts that did not click an email campaign activity. |
The default maximum number of email campaign activities to evaluate is 500. To avoid returning a 400 error response, when specifying the segment_criteria
do not request more than 500 email campaigns or a date range greater than 1825 days (5 years) be evaluated.
[CLICK] Example: Tracking Activity for Specific Campaigns
To include or exclude (eq
or ne
) contact tracking activities for one or more specific email campaigns, specify the email campaign activity ID as the value
to use for each.
"criteria": {
"type": "and",
"group": [
{
"source": "tracking",
"field": "opened",
"op": "eq",
"value": "4c08372c-957a-48b5-bc45-72c7f00796cd"
},
{
"source": "tracking",
"field": "opened",
"op": "eq",
"value": "8c04262c-957a-88b5-bc45-72c7f00886dc"
}
]
}
[CLICK] Example: Tracking Activity for Last Number of Email Campaigns
To evaluate contact tracking activities for all or any ("op":"contains-all"
or "op":"contains-any"
) of the last number of email campaigns sent, use "const_value": "last-n-campaigns"
and set the param
to the number of email campaigns to use.
Date criteria (in-range
or last-n-days
) is optional. When using last-n-campaigns
if no date is specified, the date criteria defaults to five years.
"criteria": {
"type": "and",
"group": [
{
"source": "tracking",
"field": "opened",
"op": "contains-any",
"const_value": "last-n-campaigns",
"param": 5,
"const_date_value": "in-range",
"date_param": [
"2017-12-15T01:16:00+0000",
"2018-02-28T01:16:00+0000"
]
}
]
}
[CLICK] Example: Tracking Activity for the Last Number of Days
To evaluate contact tracking activity for all or any ("op":"contains-all"
or "op":"contains-any"
) email campaigns for a specified last number of days (last-n-days
), set the "value":
of "const_value": "campaigns"
to the number of days to use.
Date criteria (in-range
or last-n-days
) is optional.
"criteria": {
"type": "and",
"group": [
{
"source": "tracking",
"field": "opened",
"op": "contains-any",
"const_value" : "campaigns",
"const_date_value": "last-n-days",
"date_param": "90"
}
]
}
Contact Data Source
The contact
data source supports and
and or
to join contact data in the segment criteria. For example, you can create a segment used to identify contacts that have a job title of Director and live in Massachusetts.
The data
source includes the following types of contact data:
-
Standard contact fields: Property fields from the contact’s profile information such as birthday month.
-
Custom contact fields: Property fields that you named and defined (must already exist).
-
System defined fields: Property fields such as the date the contact was added, date updated, and the source of the contact.
[CLICK] Example: Contact Data Segment Criteria using the UI

Use the V3 API, to specify multiple contact field
properties to include or exclude in the segment criteria (using "op":"eq"
and "op":"ne"
operations). You can also use starts-with
and contains-string
operations with value
strings. The system generated date_added
and date_updated
fields only support the contains-any
operation with const_value
for either in-range
(array of two dates) or last-n-days
(integer).
[CLICK] Example: Contact Data Segment Criteria using the V3 API
"criteria": {
"type": "and",
"group": [
{
"source": "contact",
"field": "state",
"op": "eq",
"value": "Massachusetts"
},
{
"source": "contact",
"field": "title",
"op": "starts-with",
"value": "dir"
}
]
}
List Membership Data Source
To limit the number of contacts that the segment criteria must evaluate and process, specify the contact lists to use. The list_membership
data source only supports joining list data using or
.
[CLICK] Example: List Membership Data Source Segment Criteria using the UI

[CLICK] Example: List Membership Data Source Segment Criteria using the V3 API
Specify which contact lists (list_id
) to use. To include contacts that are not on a list, set the const_value
to none
and leave the list_id
blank. If no contact lists are specified in the segment criteria, all contacts in your account are evaluated and processed. You can use or
to specify more than one list to include in the segment criteria.
"criteria": {
"type": "and",
"group": [
{
"type": "or",
"group": [
{
"source": "list_membership",
"field": "list_id",
"op": "eq",
"value": "04fe9a-a579-43c5-bb1a-58ed29bf0a6a"
},
{
"source": "list_membership",
"field": "list_id",
"op": "eq",
"value": "08bd8c-a579-43c5-bb1a-58ed29bf0a6a"
}
]
}
]
}
Tags Data Source
To include or exclude tagged contacts in the contact results, in the segment criteria, specify the tag_id
to include (eq
) or exclude (ne
). The tags
data source only supports joining list data using or
.
[CLICK] Example: Tags Data Source Segment Criteria using the UI

[CLICK] Example: Tags Data Source Segment Criteria using the V3 API
To include contacts that are not tagged, set the const_value
to none
and leave the tag_id
blank. You can use or
to specify more than one tag to include in the segment criteria.
"criteria": {
"type": "and",
"group": [
{
"type": "or",
"group": [
{
"source": "tags",
"field": "tag_id",
"op": "eq",
"value": "{tag UUID}"
},
{
"source": "tags",
"field": "tag_id",
"op": "ne",
"value": "{tag UUID}"
}
]
}
]
}
Methods and Endpoints
To create and manage segments using the V3 API, use the segment endpoints that follow.
POST /segments
To create a new segment, use the POST /segments
endpoint to specify the name
and segment_criteria
for the segment.
Related topics:
- Learn More about using this endpoint.
- Try it!
GET /segments
To get a list of all segments for an account, use the GET /segments
endpoint. You can specify the sort order for the resulting list of segments. You can sort by name (sort_by=name
) in ascending order, or sort by date (sort_by=date
) in descending order. By default, the results are sorted by date with the most recently updated segments listed first.
- Learn More about using this endpoint.
- Try it!
GET /segments/{segment_id}
To get details about a single segment, including segment_criteria
, use the GET /segments/{segment_id}
endpoint. If you know the segment_id
, this endpoint can also be used to get a deleted segment.
Related topics:
- Learn More about using this endpoint.
- Try it!
PUT /segments/{segment_id}
To update an existing segment’s name
and/or segment_criteria
, use the PUT /segments/{segment_id}
endpoint. You must specify both name
and segment_criteria
, even if you are only updating one.
Related topics:
- Learn More about using this endpoint.
- Try it!
PATCH /segments/{segment_id}/name
To rename an existing segment, use the PATCH /segments/{segment_id}/name
endpoint.
Related topics:
- Learn More about using this endpoint.
- Try it!
DELETE /segments/{segment_id}
To delete (soft-delete) a segment and the segment’s criteria, use the DELETE /segments/{segment_id}
endpoint. After deleting a segment, the name
remains available for reporting purposes. To view a deleted segment, use the GET /segments/{segment_id}
.
Related topics:
- Learn More about using this endpoint.
- Try it!
Authorization Requirements
To use the segment feature, you must have the Account Owner or Account Manager user role. The required endpoint privileges and scopes are as follows:
POST
, PUT
, PATCH
, and DELETE
:
User privileges: contacts:lists:write
Authorization scopes: contact_data
GET
:
User privileges: contacts:lists:read
Authorization scopes: contact_data
GET STARTED
To start using the segments feature, complete the high-level steps that follow.
STEP 1: Create a new segment
Create a new segment using the POST /segments
endpoint:
- Specify a unique
name
for the segment. - Specify the
segment_criteria
to use.
The system generates the segment_id
that uniquely identifies the segment.
Learn More about using this endpoint.
STEP 2: Get a segment's contact results
Prior to sending an email campaign activity to a segment, get and review the segment’s contact results to ensure it meets your contact criteria for a given campaign activity.
To get a segment’s contact results, use the GET contacts/
endpoint and specify the segment_id
to use as the query parameter (contacts/?{segment_id}
).
Learn More about contacts.
You can also chose to export the contact results to a file using the bulk activities POST /activities/contact_exports
endpoint. To import previously exported segment contact results into an existing contact list, use the POST /activities/contacts_json_import
or POST /activities/contacts_file_import
.
Learn More about using contact lists.
STEP 3: Add a segment to an existing email campaign activity
To add a segment to an existing email campaign activity, use the PUT /emails/activities/{campaign_activity_id}
endpoint. In the request body segment_ids
array, specify the segment (segment_id
) to use when sending the email campaign activity. You can only include one segment_id
. You cannot specify both a segment_id
and a list_id
.
Learn More about scheduling and sending an email campaign.
STEP 4: Send an email campaign activity to a segment
When an email campaign activity is sent to a segment, Constant Contact uses the segment_criteria
to identify the contacts that currently meet the criteria.
Learn More about scheduling and sending an email campaign activity.