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.

This release currently does not support using contact details and membership_list data sources as 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 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.

The following shows segment criteria and data source examples.

Segments overview image

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".

Create Segments image
[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",
   "segment_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:

PropertyTypeDescription
segment_idintegerThe system generated ID that uniquely identifies a segment.
name stringThe unique name that you specify for a segment.
created_atstring 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_atstringThe 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_criteriastringSpecifies 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:
  • tracking (supports "and" and "or" joins)
  • contact (supports "and" and "or" joins)
  • list_membership (supports "or" joins)

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",
     "segment_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)

Does not support: list_membership and list_membership

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": "contacts",
     "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.

Tracking activities UI image

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.

      
 "segment_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.

 
 "segment_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.

 "segment_criteria": {
      "type": "and",
      "group": [ 
         {
          "source": "tracking",
           "field": "opened",
           "op": "contains-any",
           "const_value" : "campaigns",
           "value": "5",
           "const_date_value": "last-n-days",
           "date_parm": "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
Contact data criteria image

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

  "segment_criteria": {
         "type": "and",
         "group": [
            {
              "source": "contacts",
              "field": "state",
              "op": "eq",
              "value": "Massachusetts"
            }, 
            {
              "source": "contacts",
              "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

Create Segments image
[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.

"segment_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"
         }
       ]
      }
    ]  
  }        

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:

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.

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:

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.

PATCH /segments/{segment_id}/name

To rename an existing segment, use the PATCH /segments/{segment_id}/name endpoint.

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}.

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:

  1. Specify a unique name for the segment.
  2. Specify the segment_criteria to use.

The system generates the segment_id that uniquely identifies the segment.

Learn More about using this endpoint.

Try it!

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.

You can choose to get a segment’s contact results by exporting the results to a file or by importing the results into a contact list.

Export segment results to a file

Using the bulk activities POST /activities/contact_exports endpoint:

  1. Specify the segment_id to export.
  2. Specify any contact fields that you want to include in the exported file.
  3. Optionally, specify only to include contacts with a specific status, such as active, unsubscribed, or removed.
  4. In the response body, locate the results URL link and use it to open the exported file.
  5. Verify that the contact results meet your specified segment_criteria.

Learn More about exporting contact results to a file.

Try it!

Import segment results into a new contact list

Create a new contact list and then populate the new list with the segment’s resulting contacts.

  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!
  3. Open the contact list and verify that the results meet your specified segment_criteria.

Before sending an email campaign activity, to include the most current segment contact results in a static contact list, you need to re-import the contact segments results into the list.

You can also import previously exported segment contact results into an existing contact list using 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.

Try it!

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.

Try it!