Overview of list endpoints, how to create and manage contact lists, along with adding and removing contacts.

About Contact Lists

Lists allow Constant Contact users to target and mail contacts with common interests. They also help users to manage the email addresses in their account more efficiently by focusing on one group at a time.

Constant Contact does not sell or rent email addresses. Users are not permitted to upload or use purchased, traded, shared, or borrowed lists to their Constant Contact account.

Review our permission policy for more information.

Limits

  • Users can have a maximum of 1,000 lists in their account.
  • New lists are empty until contacts are added its membership.
  • A contact can belong to a maximum of 50 lists.

New list_id Format in V3

`list_id` values are formatted as UUIDs (Universally Unique IDentifier) format, 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens). The V2 format was string.

List Management Workflow

Here is a basic list management workflow.

Determine what lists you need based on how you organize your contacts, then:

Step 1 Create a new list for each category.
Step 2 Identify which contacts to add to each list.
Step 3 Add contacts to each list.
Step 4 Maintain lists to improve open rates and reduce spam complaints.


Create a List

Step 1Create a new list using a POST call to the /contact_lists endpoint. Provide a name and description for the list, note that each list name must be unique.

Use `"favorite"=true` to flag a list as a favorite. Developers can then display favorite lists more prominently in their integration's list view.

Example POST Request

POST https://api.cc.email/v3/contact_lists

Endpoint Requirements

User privileges: contacts:lists:write

Authorization scopes: contact_data

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\n  \"name\": \"Multiple purchases\",\n  \"favorite\": \"true\",\n  \"description\": \"List of repeat customers\"\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/contact_lists")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Cache-Control", "no-cache")
  .build();

Response response = client.newCall(request).execute();
<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contact_lists');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Cache-Control' => 'no-cache',
  'Accept' => 'application/json',
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {access_token}'
));

$request->setBody('{
   "name": "Multiple purchases",
   "favorite": true,
   "description": "List of repeat customers"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
curl -X POST \
  https://api.cc.email/v3/lists \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "name": "Multiple purchases",
  "favorite": true,
  "description": "List of repeat customers"
}'

Response

{
  "list_id": "{list_id}",
  "name": "Multiple purchases",
  "description": "List of repeat customers",
  "favorite": true,
  "created_at": "2017-07-14T11:25:00-04:00",
  "updated_at": "2017-07-14T11:25:00-04:00"
}

Try it!

Populate the List - Add Contacts

Step 2 & 3If the contacts being added to the list are already in the user’s Constant Contact account, use the /activities/add_list_memberships endpoint.

Example Request - POST add_list_membership

This call adds five existing contacts to two lists. Use the contact_ids array in the source object to specify contacts. Use the list_ids array in the source object to specify lists.

POST https://api.cc.email/v3/activities/add_list_memberships

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"source\": {\n    \"contact_ids\": [\n    \t\"{contact_id1}\",\n    \t\"{contact_id2}\",\n\t\t\"{contact_id3}\",\n\t\t\"{contact_id4}\",\n\t\t\"{contact_id5}\",\n\t\t\"{contact_id6}\"\n    ]\n  },\n  \"list_ids\": [\n    \"{list_id1}\",\n    \"{list_id2}\"\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/activities/add_list_memberships")
  .post(body)
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Cache-Control", "no-cache")
  .build();

Response response = client.newCall(request).execute();
<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/add_list_memberships');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Cache-Control' => 'no-cache',
  'Accept' => 'application/json',
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {access_token}'
));

$request->setBody('{
  "source": {
    "contact_ids": [
      "{contact_id1}",
      "{contact_id2}",
      "{contact_id3}",
      "{contact_id4}",
      "{contact_id5}",
      "{contact_id6}"
    ]
  },
  "list_ids": [
    "{list_id1}",
    "{list_id2}"
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
curl -X POST \
  https://api.cc.email/v3/activities/add_list_memberships \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "source": {
    "contact_ids": [
      "{contact_id1}",
      "{contact_id2}",
      "{contact_id3}",
      "{contact_id4}",
      "{contact_id5}",
      "{contact_id6}"
    ]
  },
  "list_ids": [
    "{list_id1}",
    "{list_id2}"
  ]
}'

Response

Adding contacts to a list using the /activities/add_list_memberships endpoint triggers an asynchronous batch job. The response payload provides an activity status report.

{
    "activity_id": "activity_id",
    "state": "initialized",
    "created_at": "2018-02-28T13:49:41-05:00",
    "updated_at": "2018-02-28T13:49:41-05:00",
    "percent_done": 1,
    "activity_errors": [],
    "status": {
        "list_count": 2
    },
    "_links": {
        "self": {
            "href": "/v3/activities/activity_id"
        }
    }
}

Learn more: Add Contacts to Lists.

If the contacts being added are in a local data store, import them using one of the import contacts activity endpoints, specifying the new list in the list_ids property.

Learn more: Importing Contacts

View List Members

After adding contacts to the new list, view the list membership by making a GET call to the Contact Collection endpoint and include the optional lists query parameter to specify the list_id. The call returns all contacts who are members of the specified list(s).

Example Request - GET list membership

This GET Contacts call uses the lists query parameter to return the members of the two lists specified.

GET https://api.cc.email/v3/contacts?lists={list_id1},{list_id2}

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.cc.email/v3/contacts?lists={list_id}")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer  {access_token}")
  .addHeader("cache-control", "no-cache")
  .build();

Response response = client.newCall(request).execute();
curl -X GET \
  'https://api.cc.email/v3/contacts?lists={list_id},{list_id2}' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {access_token}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts?lists={list_id1},{list_id2}');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'lists' => '{list_id}'
));

$request->setHeaders(array(
  'cache-control' => 'no-cache',
  'authorization' => 'Bearer {access_token}',
  'content-type' => 'application/json',
  'accept' => 'application/json'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Response

{
    "contacts": [
        {
            "contact_id": "{contact_id}",
            "email_address": {
                "address": "dprice@example.com",
                "permission_to_send": "implicit",
                "created_at": "2013-11-26T15:45:42-05:00",
                "updated_at": "2013-11-26T15:45:42-05:00",
                "opt_in_source": "Account",
                "opt_in_date": "2013-11-26T15:45:42-05:00",
                "confirm_status": "off"
            },
            "first_name": "David",
            "last_name": "Price",
            "update_source": "Account",
            "create_source": "Account",
            "created_at": "2013-11-26T15:45:42-05:00",
            "updated_at": "2017-09-06T15:48:31-04:00"
        },
        {
            "contact_id": "{contact_id}",
            "email_address": {
                "address": "jprice@example.com",
                "permission_to_send": "implicit",
                "created_at": "2013-11-26T15:45:50-05:00",
                "updated_at": "2013-11-26T15:45:50-05:00",
                "opt_in_source": "Account",
                "opt_in_date": "2013-11-26T15:45:50-05:00",
                "confirm_status": "off"
            },
            "first_name": "Jennifer",
            "last_name": "Price",
            "create_source": "Account",
            "created_at": "2013-11-26T15:45:50-05:00",
            "updated_at": "2013-11-26T15:45:50-05:00"
        },
        {
            "contact_id": "{contact_id}",
            "email_address": {
                "address": "joe.jones@example.com",
                "permission_to_send": "implicit",
                "created_at": "2017-11-06T15:35:30-05:00",
                "updated_at": "2017-11-06T15:35:30-05:00",
                "opt_in_source": "Account",
                "opt_in_date": "2017-11-06T15:35:30-05:00",
                "confirm_status": "off"
            },
            "first_name": "Joe",
            "last_name": "Jones",
            "job_title": "Chief Innovation Officer",
            "company_name": "RelativeGravity, Inc.",
            "birthday_month": 11,
            "birthday_day": 24,
            "anniversary": "2006-11-15",
            "create_source": "Account",
            "created_at": "2017-11-06T15:35:30-05:00",
            "updated_at": "2017-11-06T15:35:30-05:00"
        },
        {
            "contact_id": "{contact_id}",
            "email_address": {
                "address": "mmiller@example.com",
                "permission_to_send": "implicit",
                "created_at": "2013-11-26T15:46:04-05:00",
                "updated_at": "2013-11-26T15:46:04-05:00",
                "opt_in_source": "Account",
                "opt_in_date": "2013-11-26T15:46:04-05:00",
                "confirm_status": "off"
            },
            "first_name": "Mike",
            "last_name": "Miller.",
            "create_source": "Account",
            "created_at": "2013-11-26T15:46:04-05:00",
            "updated_at": "2013-11-26T15:46:04-05:00"
        },
        {
            "contact_id": "{contact_id}",
            "email_address": {
                "address": "sheryl.kavanaugh@example.com",
                "permission_to_send": "implicit",
                "created_at": "2013-11-26T15:46:10-05:00",
                "updated_at": "2013-11-26T15:46:10-05:00",
                "opt_in_source": "Account",
                "opt_in_date": "2013-11-26T15:46:10-05:00",
                "confirm_status": "off"
            },
            "first_name": "Sheryl",
            "last_name": "Kavanaugh",
            "create_source": "Account",
            "created_at": "2013-11-26T15:46:10-05:00",
            "updated_at": "2013-11-26T15:46:10-05:00"
        }
    ]
}

Try it!

Remove Contacts from the List

Step 4It’s a good practice in maintaining lists to remove stale contacts from lists in order to improve campaign open rates and to avoid list compliance reviews due to too many bounces. Use the /activities/remove_list_memberships endpoint to remove large numbers of contacts from one or more existing lists.

Learn more.