Lists

Used for:

•  Message Content
•  Building Audiences
•  Triggering Messages
•  Analytics

Lists Overview

Lists are used to segment your contacts in a way that relates 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 view stats over time.

• 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

Using Lists for Building Audiences

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

You are able to build 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 with Lists

Using Audience Trend Reports, you can view the population of an audience over time using 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.

Learn more about Audience Trends

In the next article learn about cart items.