Create a new segment.

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 the tracking 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 the contact 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). The tags data source only supports joining list data using or.)

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.

Try it!

Save a Segment’s Contact Results to a Contact list

You can choose to save a segment’s resulting contacts to a contact list:

  1. Create a new contact list using the POST /contact_lists endpoint.
    Try it!
  2. 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"
 }

Try it!