# How can we help? ## 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](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#messageContent), [build audiences](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#audiences), [trigger messages](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#trigger), and [create analytics reports](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#analytics). 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" } ] ``` ## Create a list You can create lists in Cordial two different ways: - [Via the UI](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#ui) - [Via the API](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#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](https://support.cordial.com/hc/en-us/articles/10546029940109#h_01GHYKKKQY53X8QSGQV2QMWMY2). 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](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#h_01GJ3Q0TS0F04ZHY9BW9GYYKTS) - [Set email subscription status](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#h_01GJ3MTQY089KZEE0SJ4SJESX7) - [Populate an attribute](https://support.cordial.com/hc/en-us/articles/115005528428-Lists#h_01GJ3Q1WMD80YAG78ERV590GJC) These updates can be performed during your initial mapping setup or after your Data Job has started running. 1. In **Data Mapping**, click the **plus icon** to add a list column for the bulk action you want to perform. 2. 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 subscribed - 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](https://support.cordial.com/hc/en-us/articles/204570497-Account-Lists#postAccountLists). - You can update a contact's list membership via the API using the [POST/contacts](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#postContacts) and [POST/contactimports](https://support.cordial.com/hc/en-us/articles/203886058-Contact-Imports#postContactImports) 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). ## 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_. ## 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](https://support.cordial.com/hc/en-us/articles/227853327-Welcome-Message). 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. ## 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](https://support.cordial.com/hc/en-us/articles/115005364907) for each list, and then viewing them on the [Audience Trends chart](https://support.cordial.com/hc/en-us/articles/115005364907-Audience-Trends). ### Filter event dashboards [Event dashboards](https://support.cordial.com/hc/en-us/articles/115005533188) 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. ### Filter event data reports [Event data reports](https://support.cordial.com/hc/en-us/articles/115005533268-Event-Data-Reports) allow you to view reports of event activity. You can filter reports using audience rules similar to the event dashboard charts. ## 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.