Provides an overview of list endpoints and the list workflow.

Create contact lists to logically add and group contacts that have one or more things in common, such as interests, job titles, or birthdays. To send an email campaign activity to members of a contact list, update the activity to specify which contact list(s) to use.

Creating lists that specifically target your contacts interests or needs, results in better campaign performance (opens, clicks, shared links, etc.) and lower opt-outs.

Use Case Example

Say you want to create and send an email campaign to target only those contacts that are tagged as dog owners and that have birthdays in May. There are several ways to identify and add contacts to the new list.

You choose to create a segment to use to evaluate and identify which contacts to target. You set dog lovers and the birthday month of May as the segment criteria. Because segments are dynamic, results will vary depending on when the segment is requested to evaluate your contacts.

  • If you assign the segment to the email campaign activity, contacts are evaluated and identified at the point-in-time that the campaign is scheduled to be sent.

  • If you assign a list to the email campaign activity, contacts are evaluated and identified at the point-time-time that you request an activity that adds a segments resulting contacts to the list.

You decide to create a list and specify the list as the contact source for the email campaign activity to use.

Lists are static. Adding contacts to a list allows you keep a record of contacts that were sent your campaign. If you create a second list using the same segment at a different point-in-time, you can use it to gain insights about contact membership changes.

For more information about using segments, see the Segments Overview.

Contact List Workflow and Endpoints

STEP 1: Create a Contact List

To create a new contact list, make a POST call to the contact_lists endpoint. You must provide a unique name for the list. You can have a maximum of 1,000 lists in your account and a contact can belong to a maximum of 50 lists.

Learn More

Try it!

STEP 2: Add Contacts to Lists

There are several ways that you can add contacts to one or more lists.

Add a Single Contact to Lists

In the request body, use the list_memberships array to add a contact to up to 50 lists by making a:

  • POST call to /contacts endpoint to create a new contact. Try it!

  • PUT call to /contacts/contact_id to update an existing contact . Try it!

Add a Large Number of Contacts to Lists

To quickly add a large numbers of contacts to one or more existing lists, use asynchronous activity endpoints.

POST /activities/add_list_memberships

To quickly add a large numbers of contacts to one or more existing lists, make a POST call to the /activities/add_list_memberships endpoint. Use the properties in the source object to specify the contacts you want to add to lists. This endpoint allows you to specify the contacts to add to lists in one of five mutually exclusive ways:

  • contact_ids - an array of up to 500 individual contact_id values.
  • list_ids - an array of up to 50 individual list_id values. All contacts that are members of these “source” lists will be added to the “destination” lists.
  • all_active_contacts - a boolean that, when set to true, adds all active (billable) contacts in the user’s account to the “destination” lists.
  • segment_id - system generated segment ID (integer) used to get all contacts that meet the specified segment’s criteria. 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.
  • tag_ids - an array of up to 50 tag_ids used to identify which tagged contacts to add to the destination lists.

Learn More

Try it!

POST /activities/contacts_file_import

When importing contacts from a CSV file, use the list_ids query parameter to add contacts to specified lists (up to 50). Try it!

POST /activities/contacts_json_import

When importing contacts from a JSON payload, in the request body use the list_ids array to add imported contacts to specified lists (up to 50). Try it!

STEP 3: Add Lists to an Email Campaign Activity

An email campaign activity is designed to target contacts on one or more of your lists. You specify which lists to use when you schedule an email campaign activity to be sent. You currently cannot add contacts when you initially use the POST /emails method to create the campaign. Use PUT /emails/activities/{campaign_activity_id} to add contacts to an email campaign activity using the contact_list_ids array or the segments_ids array.

Learn More

Try it!

STEP 4: List Management

Use the following list endpoints to view and maintain your lists:

View Lists

  • Single List: To get details about a specific contact list (list_id), make a GET call to the /contact_lists/{list_id} endpoint.

    Learn More

    Try it!

  • Get All Lists: To get details about all contact lists in your account, make a GET call to the /contact_lists endpoint.

    Learn More

    Try it!

Update a List

To update an existing contact list’s name, description, or favorite list status, make a PUT call to the contact_lists/{list_id} endpoint.

Learn More

Try it!

Delete a List

To delete a list, make a DELETE call to the /contact_lists/{list_id} endpoint. This request updates a contacts list memberships, it does not delete the contact.

Learn More

Try it!

Review Members of a List

To get contact membership details for a particular list, make a GET call to the /contacts?lists={list_id1} endpoint. Use the lists query parameter to specify which lists to use. The response includes contact details, such as contact_id, first_name, last_name, job_title, and more.

Learn More

Try it!

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.