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.

  • Tags (tags): To include or exclude contacts based on tags, specify the tags (by tag_id) to use in the segment criteria.

The following shows segment criteria and data source examples.

Segments data sources

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)
  • tags (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)
  • (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": "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"
         }
       ]
      }
    ]  
  }  
        

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

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

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

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.

Related topics:

PATCH /segments/{segment_id}/name

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

Related topics:

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:

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.

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.

Try it!

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.

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!