Overview

Lists allow you to segment contacts in ways relevant to your business. List names may relate to subscriptions such as newsletter or weekly specials, brand affinity and engagement, types of membership like VIP or western region, and much more. Lists can be used to personalize message content, build audiences, trigger messages, and create analytics reports.

When creating lists, keep in mind that:

• A contact can be associated with one or more lists.
• There is no limit to how many lists can be created.
• List names must be unique from other list names as well as contact attribute names.

Unlike audiences, lists are static in nature. Contacts will retain their list membership until they are removed from the list. Audiences are dynamic, and their populations can change automatically over time depending on the rules used to create them.

How Cordial stores lists

A contact's list association is stored in the contact's record within the contacts collection. Below is a simplified example of how list association is stored in Cordial's database as part of a contact record.

• The lists attribute is stored as an array in the contact record.
• This contact is a member of the lists newsletter and weekly_specials.

[
  {
    "channels": {
      "email": {
        "address": "fredgarvin@example.com",
        "subscribeStatus": "subscribed",
      }
    },
    "firstName": "Fred",
    "lastName": "Garvin",
    "gender": "male",
    "lists": [
      "newsletter",
      "weekly_specials"
    ],
	"listJoinDate": {
      "newsletter": "2017-03-13T17:50:46+0000",
      "weekly_specials": "2017-03-13T17:50:46+0000"
    },
    "_id": "58c6dae96e05abd5fef72184"
  }
]

Create a list

You can create lists in Cordial three different ways:

• Via the UI
• Via a CSV upload
• Via the API

If you have a large number of lists, we recommend that you create them in the UI prior to uploading contacts. This creates a better user experience.

Create a list via the UI

1. Log in to the Cordial platform and navigate to Data > Lists.

2. Select the New button to create a list.

3. Complete the fields for List name and Date Tracking.

We recommend that you select Date Tracking to allow for automation trigger rules where the condition is "contact being added to a list." For example, a welcome message that sends an email three days after a contact joins the Newsletter list.

Create a list via CSV upload

Lists can also be created when importing contact records.

1. Prepare a CSV file where the header row contains the names of the lists you would like to add to the system, and place a 1 or a 0 in the row for each contact. This will tell the system whether a contact is on a list (1=true), or not on a list (0=false).

List names cannot contain spaces and should be all lowercase. If your file contains more rows, make sure there is either a 1 or a 0 in each list column. Otherwise, errors may result.

2. Follow the steps described in this article to import contacts via data job.

3. While configuring Data Mapping for your CSV file, click the plus icon to add a list column. 

3. In the Select column type dropdown, choose Add to list and then select Create new list from the second dropdown.

4. Give your list a name and click Save.

Create a list via the API

You can create a list via the API using the POST /accountlists API call.

You can update a contact's list membership via the API using the POST /contacts and POST /contactimports API calls.

View and edit a list

Navigate to Data > Lists to view all lists created in your account.

Hover over the arrow next to each list name to see the options:

• Remove: Removes the list from the system.
• Edit: Updates the name and date tracking option of the list.
• Clear: Removes all contact list associations while keeping the list in the system (changes the contact's boolean value for that list from a 1 to a 0).

When a list is removed or cleared, no contacts will be deleted from the system.

Use lists for message content

While you can render list names in a message, you'll most likely use list membership as a way to display dynamic content.

Use case

If a contact is a member of the Gold list, you'd want to show Gold content. If a contact is a member of the Silver list, you'd want to show Silver content.

You would use the following Smarty code to display the above use case.

{if in_array('gold', $contact.lists)}
Gold Content
{if in_array('silver', $contact.lists)}
Silver Content
{/if}

During message creation, it is useful to use the following Smarty utility to view the contact record in JSON format: {$utils->jsonPrettyPrint($contact)} By pasting the above code into the HTML editor and clicking the Preview button, you can view the specified contact's record with all attributes, list association, and cart items (if available).

• You can learn more about using "if" statements in Smarty here.

Use lists to build audiences

Using the List audience rule, you can build audiences based on list membership.

1. Navigate to Contacts > Audience and edit or create a new audience.

2. Select Lists from the Rules dropdown in the Audience Builder.

3. Drag the list rules you want to use into your audience.

Use case

You can create complex segmentation queries by combining list audience rules with other rules to create queries such as All women contacts with a denim affinity.

• You can learn more about the Audience Builder here.

Use lists to trigger messages

You can trigger automated messages based on when a contact is added to a list. This is useful for welcome message campaigns.

1. Select or create a message automation: Cordial Dashboard > Message Automation. 

2. In the Message creation dashboard, navigate to Sending Methods > Event Triggered in the left sidebar.

3. From the Trigger Events pane, choose When a contact is added to a list for the trigger event.

Date Tracking must be enabled for the list you want to use as a trigger.

• You can learn more about automated messages here.

Build analytics reports using lists

Audiences based on list membership can be saved as audience rules and either visualized over time with audience trend reports, or used as filters for event data dashboards and event data reports.

Audience Trend reports

To access audience trend reports, log in to Cordial and navigate to Analytics > Audience Trends. From here, you can view the population of an audience over time, based on their list membership.

Use case

You could compare audiences of contacts that are on the 12_month_buyers and High_Brand_Engagement lists (as shown below) by enabling Audience Trend analytics for each list, and then viewing them on the Audience Trends chart.

Filter event dashboards

Event dashboards provide a way to visualize event activity over time by creating customizable charts. You can take advantage of list membership in event dashboard charts using audience filters. 

To edit an event chart (also called a time series chart), navigate to Analytics > Event Dashboards and select Chart Settings in the upper right corner of the chart.

Use case

You could create a chart that plots message activity over time filtered by a saved audience rule where the contact is on the 12_month_buyers list.

Filter event data reports

Event data reports—navigation: Analytics > Event Data Reports—allow you to view reports of event activity. You can filter reports using audience rules similar to the event dashboard charts.

Use case

You could filter by a saved audience rule where the contact is on the 12_month_buyers list.

In the next article, you can learn about cart items.