Lists

Used for:

•  Message Content
•  Building Audiences
•  Triggering Messages
•  Analytics

Lists Overview

Lists allow you to segment your contacts in ways that relate to your business. List names may relate to subscriptions such as Newsletter or Weekly Specials or types of membership like VIP or Western Region. Lists can be used to personalize message content, build an audience, trigger messages and create analytics reports.

• 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.

It's important to note that, unlike audiences, lists are static in nature. Contacts will 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 that are used to create them.

How Lists Are Stored

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. To help with visualization we highlighted the portion pertaining to lists.

[
  {
    "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"
  }
]

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

How to Create a List

Lists can be created in Cordial:

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

Creating a list via the UI

1. Log into the Cordial platform and navigate to Data › Lists.
2. Click the button labeled New.
   
   
3. Fill out fields for List Name and Date Tracking.
   
   Note: It is recommended to select Date Tracking to allow for automation trigger rules that depend on when a contact was added to a list. For example: A welcome message that sends an email 3 days after a contact joins the Newsletter list.

Creating a list via a 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).
   
   
   Note:
   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 or errors may result.
2. Log into the Cordial platform and navigate to Contacts › Import Contacts.
   
   
3. Click the button labeled New and fill out the form to import the file.
   
   
   • Import Source - select whether the source is a local file or hosted remotely.
   • Header Row - select if your data file has a header row. It is recommend to use a header row to make it easier to match the columns with their corresponding attributes when importing.
   • Choose Delimiter
4. Select and upload your CSV.
5. You'll then have the option to Add List for each header row column you have created.
   
   
   Note: If a list with the same name is already in the system, it will be automatically mapped to the correct list.

Creating 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.

Viewing and Editing 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 association while keeping the list in the system (changes the contact's boolean value for that list from a 1 to a 0).

Using Lists for Message Content

While you are able to render list names in a message, you are most likely going to use list membership as a way to display dynamic content.

For example: If contact is a member of the list Gold, show "Gold Content", else if a contact is a member of the list Silver, show "Silver Content".

You would use the following Smarty code to display the above example:

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

Learn more about using "if" statements in Smarty

{$utils->jsonPrettyPrint($contact)}

Using Lists for Building Audiences

Using the List audience rule, you are able to build audiences based on list membership.

You can create complex segmentation queries by combining list audience rules with other rules to create queries such as: "Show me all male contacts on the Gold list that have more than $40 in their cart.

Note below the List audience rule highlighted on the audience builder:

Learn more about the audience builder

Using Lists for Triggering Messages

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

To trigger an automated message based on list membership, use the Event Triggered sending method, and choose the Trigger Event: "When a contact is added to a list".

Note that Date Tracking must be enabled for the list you would like to use as a trigger.

Learn more about automated messages

Building 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

Using audience trend reports, you can view the population of an audience over time based their list membership.

For example, you could compare audiences of contacts that are on the Silver, Gold and Platinum lists by enabling audience trend analytics on each one, and 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.

For example, you can create a chart that plots message activity over time filtered by a saved audience rule where the contact is a member of the Newsletter_List.

Filter Event Data Reports

Event data reports allow you to view reports of event activity. You are able to filter reports using audience rules similar to event dashboards. For example you can filter by a saved audience rule where the contact is a member of the Newsletter_List.

In the next article learn about cart items.