Create contact lists to logically group and target contacts that have one or more things in common, such as interests, job industries, or birthdays. New lists are empty until contacts are added as members.
An account can have a maximum of 1,000 lists and a contact can belong to a maximum of 50 lists.
To create a new list, make a POST call to the /contact_lists
endpoint. In the request body, specify the following list details:
name
: Provide a unique name for the list. (Required)favorite
: To allow developers to display favorite lists more prominently in their integration’s list view, set thefavorite
value totrue
. The default isfalse
. (Optional)description
: Provide a brief description for the list, using up to 255 characters. (Optional)
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"
}'
Example Response
{
"list_id": "{list_id}",
"name": "Multiple purchases",
"description": "List of repeat customers",
"favorite": true,
"created_at": "2022-07-14T11:25:00-04:00",
"updated_at": "2022-07-14T11:25:00-04:00"
}
list_id
: The response includes thelist_id
value associated with the new list in UUIDs (Universally Unique IDentifier) format; 8-4-4-4-12 with a total of 36 characters (32 alphanumeric characters and four hyphens).name
: The name of the list.favorite
: Identifies whether or not the list is a favorite (true
orfalse
).created_at
: The system generated date and time that the resource was created, in ISO-8601 format.-
updated_at
: The system generated date and time that the resource was last updated, in ISO-8601 format.Because this is a new list, the
created_at
andupdated_at
timestamps are identical.
What’s Next
After you create a new list and add contacts to that list, you can create email campaigns that specifically target the contacts on those lists.
To add contacts to a list:
-
If the contacts being added to the list are already in the your Constant Contact account, make a POST call to the
/activities/add_list_memberships
endpoint.To learn more, see, How to Add Contacts to Lists.
-
If the contacts being added to the list are not already in your Constant Contact account, you can import them from another source using a CSV or JSON payload. Use the following endpoints to import thousands of contacts using a single API call:
-
From a CSV payload, make a POST call to the
/activities/contacts_file_import
endpoint. -
From a JSON payload, make a POST call to the
/activities/contacts_json_import
endpoint.
To learn more, see Import Contacts.
-
For information on syncing contact data, see the Guidelines for Importing Contacts.
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.