Create segments to target a subset of your contacts that meet your specific criteria for a particular marketing campaign. For example, your campaign might be used to target and reward your most engaged contacts, welcome new contacts, or to re-engage inactive contacts.
After you create a segment, you can choose to:
- Assign a segment to a campaign
- Review the segment’s results.
- Save the segment contact results to a contact list.
Create a Segment
To create a segment, use the POST /segment
method and specify the name (name
) that uniquely identifies the segment and the segment criteria (segment_criteria
) that Constant Contact uses to dynamically evaluate and identify only those contacts that currently meet your segment_criteria
.
Name the Segment
Choose a segment name that is unique and descriptive. The system returns a 409 error response message if the segment name that you specify already exists in your account.
Specify the Segment Criteria
You can specify the contact related data to use as segment criteria from the following data sources:
-
Tracking activities (
tracking
): Constant Contact tracks how a contact interacts with your past campaigns. To include or exclude 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. -
Taggings (To include or exclude tagged contacts in the contact results, in the segment criteria, specify the
tag_id
to include (eq
) or exclude (ne
). Thetags
data source only supports joining list data usingor
.)
For example, you might create a segment that is used to identify contacts that opened one or more of your last five email campaigns to send them a targeted follow-up campaign. In the segment_criteria
, you specify data (field
) to use and the source of the data (source
). The JSON example that follows uses contact tracking activities (available from the tracking
data source) to identify contacts that opened (field
is opened
) any of your last five campaigns.
Example POST /segment
request body
{
"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\"}]}}"
}
Example POST /segment
response body
{
"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 you first create a segment, the created_at
and edited_at
timestamps are identical.
You can group data from different data sources using and
.
Learn More about segment data sources and grouping segment criteria.
Use a Segment
Assign a Segment to a Campaign
After you create a segment, the system generates the segment ID (segment_id
) that uniquely identifies the segment. You use the segment_id
to associate a segment to a campaign(s).
For example, to add a segment to an email campaign activity, use the PUT /emails/activities/{campaign_activity_id}
endpoint and in the request body segment_ids
array, specify the segments (segment_id
) to use when sending the email campaign activity. You can only include one segment_id
and you cannot specify both a segment_id
and a contact list_id
.
Example PUT /emails/activities/{campaign_activity_id}
request body
{
"campaign_activity_id": "1b1fcfb1-1e79-482e-8feb-5e603a2c54a1",
"campaign_id": "7fdf35f7-0694-491d-aece-3122992cf721",
"role": "primary_email",
"segment_ids": [
16
],
"current_status": "DRAFT",
"format_type": "4",
"from_email": "jake.dodge@gmail.com",
"from_name": "Jake Dodge",
"reply_to_email": "jake.dodge@gmail.com",
"subject": "Holiday Special Newsletter",
...
Learn More about scheduling and sending an email campaign activity.
Review a Segment’s Resulting List of Contacts
To review a segment’s resulting list of contacts, you can export the results to a file using the bulk activites POST /activities/contact_exports
endpoint. Specify the segment_id
to use in the segment_ids
array and add the fields you want to include in the exported file.
Example POST /activities/contact_exports
request body
{
"contact_ids": [
""
],
"segment_ids": [
"4"
],
"fields": [
"email_address"
],
"status": "unsubscribed"
}
The response body includes the URL link to the results
file. Use the self
link to check the state of the activity and confirm that it is completed
.
Example POST /activities/contact_exports
response body
{
"activity_id": "3d72da26-2115-11ea-9216-fa163e6b01c0",
"created_at": "2019-12-17T16:36:09-05:00",
"updated_at": "2019-12-17T16:36:09-05:00",
"percent_done": 100,
"activity_errors": [],
"status": {
"items_total_count": 149,
"items_completed_count": 149
},
"_links": {
"self": {
"href": "/v3/activities/3d72da26-2115-11ea-9216-fa163e6b01c0"
},
"results": {
"href": "/v3/contact_exports/3d713270-2115-11ea-9216-fa163e6b01c0"
}
}
}
Unlike contact lists, segments are dynamic. Depending on the criteria you specify, if the data changes, so will the results. For example, if you specify tracking data in the segment criteria to include only contacts that opened a particular campaign and over time more contacts open the campaign, the number of resulting contacts would increase.
-
Learn More about exporting contact results to a file.
-
Learn More about getting the status of a bulk activity.
Save a Segment’s Contact Results to a Contact list
You can choose to save a segment’s resulting contacts to a contact list:
- Create a new contact list using the
POST /contact_lists
endpoint.
Try it! - Add segment contact results, formatted as a JSON array, to the contact list using the
POST /activities/add_list_memberships
endpoint.
Try it!
Learn More about how to use contact lists.
Authorization Requirements
User privileges: contacts:lists:write
Authorization scopes: contact_data
Parameters
Using the PUT /segment
endpoint, specify the segment’s unique name
and segment_criteria
in the request body. The segment_criteria
must be entered as single-string escaped JSON.
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 . |
Example POST Segment Request
POST https://api.cc.email/v3/segments
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/segments');
$request->setMethod(HTTP_METH_POST);
$request->setQueryData(array(
'name' => 'test'
));
$request->setHeaders(array(
'cache-control' => 'no-cache',
'Connection' => 'keep-alive',
'Content-Length' => '267',
'Host' => 'host_name',
'Cache-Control' => 'no-cache',
'Authorization' => 'Bearer {access_token}',
'Content-Type' => 'application/json',
'Accept' => '*/*'
));
$request->setBody('{
"name":"Opened any of my the last 5 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\\"}]}}"
}
');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X POST \
'https://api.cc.email/v3/segments \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: 'Bearer {access_token}' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 267' \
-H 'Content-Type: application/json' \
-H 'Host: {host_name}' \
-H 'cache-control: no-cache' \
-d '{
"name":"Opened any of my the last 5 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\"}]}}"
}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \n\"name\":\"Opened any of my the last 5 campaigns\", \n\"segment_criteria\":\"{\\\"version\\\":\\\"1.0.0\\\",\\\"criteria\\\":{\\\"type\\\":\\\"and\\\",\\\"group\\\":[{\\\"source\\\":\\\"tracking\\\",\\\"field\\\":\\\"opened\\\",\\\"op\\\":\\\"contains-any\\\",\\\"const_value\\\":\\\"last-n-campaigns\\\",\\\"param\\\":\\\"5\\\"}]}}\"\n}\n");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/segments")
.post(body)
.addHeader("Accept", "*/*")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.addHeader("Cache-Control", "no-cache")
.addHeader("Host", "host_name")
.addHeader("Accept-Encoding", "gzip, deflate")
.addHeader("Content-Length", "267")
.addHeader("Connection", "keep-alive")
.addHeader("cache-control", "no-cache")
.build();
Response response = client.newCall(request).execute();
Response
{
"name": "Opened any of my the last 5 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": 27,
"created_at": "2020-01-21T15:25:52.000Z",
"edited_at": "2020-01-21T15:25:52.000Z"
}