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": "2025-03-13T17:50:46+0000",
      "weekly_specials": "2025-03-13T17:50:46+0000"
    },
    "_id": "58c6dae96e05abd5fef72184"
  }
]

• You can find additional list storage information below.

Create a list

You can create lists in Cordial two different ways:

• Via the UI
• 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 in the UI

Creating a list in the UI involves two main steps: creating the list and then mapping data to it.

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 your newsletter list.

4. Once you've created your list, you can map data to it during the process of importing contacts via Data Job (see below).

Map CSV data to list during contact import

1. Prepare a CSV file where the header row contains the names of the lists you would like to add to the system.

List names cannot contain spaces and should be all lowercase.

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 + button to add a list column. 

When you click the + button to add a list column, Cordial automatically places a 1 or 0 in the row for each contact to tell the system whether a contact is on the list (1=true) or not (0=false).

4. In the Select column type dropdown, choose Add to list and choose the appropriate list. You can also select Create new list from the second dropdown to create a new list when mapping your data.

Perform bulk list updates

When importing contacts via Data Job, you can perform bulk list updates and apply changes to all importing contacts without having to go back and alter your CSV file. You can also create new lists.

• Add to/ Remove from list
• Set email subscription status
• Populate an attribute

These updates can be performed during your initial mapping set up or after your Data Job has started running.

Contact your CSM to have the bulk update feature enabled.

2. In Data Mapping, click the plus icon to add a list column for the bulk action you want to perform. 

3. In the Select column type dropdown, select from the following update options:

• Add to list 
• Remove from list
• Set email subscription status
• Populate an attribute

Add to/ Remove from list

The Add to/ Remove from list actions allow you manage list content during the import. Once you've selected Add to list or Remove from list, you'll see a dropdown containing all existing lists in the system.

You can also add a new list to a Data Job. Choose Add to list and then select Create new list from the second dropdown.

Set email subscription status in bulk

You can set email subscription status in bulk by adding a new data column and selecting Set email subscription status.

You can apply several bulk update actions at the same time, but email subscription status can only be set once in a job.

For New Contacts you can:

• Set as subscribed
• Set as unsubscribed
• Set as status 'none'

For Existing Contacts you can:

• Leave as is (do not update)
• Set as subscribe
• Set as unsubscribed

Setting previously unsubscribed contacts to subscribed is in violation of the CAN-SPAM Act and can result in non-compliance. 

Populate an attribute

You can update an attribute for all imported contacts at the same time. Select Populate an attribute, and choose the name of the attribute to be populated from the dropdown. You can also create a new attribute and set a value for it by selecting Create a new attribute from the dropdown.

The bulk update action is only applicable to string, number, and date attributes (not for arrays or geo locations).

Create lists via the API

• You can create lists 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 lists

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.

Additional storage information

The Cordial database is a single unified database of all contacts and is not partitioned by separate lists.

For example, if you imported List-A that had 100 contacts, followed by List-B that had 100 contacts that were different, you would now have 200 contacts in the database. However, if List-B had 50 of the same contacts as List-A, the net amount of contacts in the database would be 150.

To preserve the relationship of lists, Cordial provides a list data type to associate a contact with a list. When importing a file of contacts, it is possible to identify contacts to the list they originated from. Using Cordial's Audience Builder, you can then select all contacts that are on one list or multiple lists. So in the previous example where we had a net of 150 contacts in the database, we could still query List-A and List-B separately and get a count of 100 for each.