Adding Users and Creating Lists

To add users to your Iterable projects and ensure that you're sending campaigns to the right groups of people, you'll create and manage lists. For high-level information about lists, see Lists Overview.

# In this article

# Creating a new list

There are three ways to create lists in Iterable:

• Upload CSV data on the Audience > Lists page.
• Save the results of a search on the Audience > Segmentation page.
• Make a call to Iterable's API.

# From the Lists page

You can import a CSV file that contains your users' data, or enter the CSV values for your users manually in the text area. Before you import a CSV file, review it to make sure it meets the following conditions:

• The list must have a unique identifier field. This may be email, userId, or in some cases both (where both are used and only one of the two is required). You can't import users without a unique identifier. If you're unsure which unique identifier your project uses, see Project Types and Unique Identifiers.

• It's a best practice to avoid leaving spaces between field names/values in the header and rows of your CSV and when manually typing in the data — especially for fields with the long data type.

• A single CSV file may include up to two million users (as rows of data). If you have more than two million users to add/update, split them into multiple files and upload each file separately.

To create a static, suppression, or internal list, go to Audience > Lists.

1. Click Import List.

   

2. Name your list, add a description if you'd like, and choose the type of list to create.

   NOTE

   The list description field has a max character count of 140. You can add special characters here, and emojis too! 🤩

3. Select the options you'd like to enable:

   

   • Blank list: A list that doesn't contain any users when you first create it. Blank lists can be useful for tracking purposes. For example, you could use a blank list to track how many users have reached a particular point in a journey (using a List Membership tile).

   • Update existing users only: Any new users that are included when you import additional user data into the list are ignored.

   • Trigger journeys from this list: When you update a list, you can add new users to the list and/or update the user profile data of users who are already on it. With this option enabled, any users who are added or updated are automatically added to journeys that are set up with the Event Occurs > Subscribe to List entry source and linked to this list. If you don't want updates to this list to add users to journeys, leave this option turned Off.

4. Click Next, then choose how to enter user information:

   • Drag and drop a CSV file into the window.

   • Select a CSV file from your computer.

   • Manually enter the list data.

5. Click Next to advance to the Review page. Here, you can verify that the details of your list are correct.

   

   The Review page also shows you the new user fields that will be added to your Iterable project because of your CSV upload. In this example, month and birthMonth will be added (shown in green text to the right of New user fields to be added).

   During the list import process, Iterable also provides a list of dropped fields (if any). When a project is set to Drop Unrecognized User Fields, Iterable rejects fields with names that don't already exist in the project and the data is dropped. This setting is useful for maintaining data integrity and preventing data pollution. To learn more about this setting, read Data Schema Management Overview.

   Unless set in a specific format, new users fields are set as strings by default. You can set three data types within the Create List page: string, boolean, and date. Dates should be in one of the following formats if setting via the UI: YYYY-MM-DD HH:MM:SS or YYYY-MM-DD.

   WARNING

   You cannot change the name or data type of user fields once they have been created. Once a user field is set as a certain type, it is permanently that type. You also can't delete user fields once they have been created.

   For more information on field data types, see Field Data Types.

6. Once everything looks correct, click Upload Subscribers. Then, on the Results page, you can view the list, check the details of your list, or upload another list.

   If the upload was successful, you should see this:

   

   If your upload is unsuccessful, check out the Tips and Best Practices section for troubleshooting help.

# From the Segmentation page

To learn how to create and save lists from the Segmentation page, see Segmentation Overview.

# Using Iterable's API

To create a new list using Iterable's API, make a call to the POST /api/lists API endpoint and include a name and description in the request body.

# Adding users to an existing list

# From the Lists page

To add more users to an existing list or update users who are already on it:

1. Go to Audience > Lists.

2. Find your list and click Add Subscribers / Modify List.

   

3. Upload a CSV file containing the new users, or input the fields manually to add users to this list.

# Using Iterable's API

You can add users to an existing list by making a call to the POST /api/lists/subscribe endpoint.

# From a journey

You can add users to an existing list when they reach a certain stage of a journey.

1. Create or open a journey.

2. Add a List Membership tile at the stage of the journey where you want to remove users from one of your lists.

3. In the tile settings menu, select Remove User From for the Action.

4. Under Audience List, select the list users should be removed from.

   

5. Click Update to save the tile settings.

6. Publish and turn on the journey to start sending users through the tile.

You can also automatically add users to a journey when they join a static list. To set this up, choose the Event Occurs > Subscribe to List entry source in the journey's Start tile and select the name of the list.

# Removing users from a list

# From the Lists page

1. Go to Audience > Lists.

2. Hover over the list from which you'd like to remove users, and click Remove Subscribers.

3. Upload a CSV or manually enter a list of the users that you'd like to remove.

4. Click Remove Subscribers.

# Using Iterable's API

To remove users from an existing list, make a call to the POST /api/lists/unsubscribe endpoint.

# From a journey

You can remove users from an existing list when they reach a certain stage of a journey.

1. Create or open a journey.

2. Add a List Membership tile at the stage of the journey where you want to add users to one of your lists.

3. In the tile settings menu, select Add User To for the Action.

4. Under Audience List, select the list users should be added to, or create a new one.

   

5. Click Update to save the tile settings.

6. Publish and turn on the journey to start sending users through the tile.

You can also automatically add users to a journey when they unsubscribe from a static list. To set this up, choose the Event Occurs > Unsubscribe from List entry source in the journey's Start tile and select the name of the list.

# Deleting a list

Before deleting a static list, we recommend removing all users from the list. To do this, open the list and click the Other Actions button. Then select Remove Contacts from List and follow the steps you're prompted to take.

Once you've started the deletion process, go back to the Lists page and check the Contacts column. It may take a few moments for all of the users to be removed, and you might need to refresh the page. Once the number of contacts on the list is 0, click the trash can icon next to the list to delete it.

To delete a dynamic list, you don't need to remove the users from the list first — simply click the trash can icon on the Lists page to delete the list. This deletes the segmentation query that determines whether or not users are eligible to be on the dynamic list, so all users are automatically removed.

# Tips and best practices

# Migrating subscribers from another email service

CSV uploads can be a useful way to migrate subscribers from another service. To learn more, see Migrating Subscribers from Another Email Service via CSV Uploads.

# Best practices for importing CSV files

To learn more about importing lists with CSV files, check out CSV List Import Best Practices.

# Invalid unique identifiers

User records that don't meet Iterable's validation requirements for the email or userId fields are not imported.

To learn more about unique identifiers based on your project type, read Project Types and Unique Identifiers.

# Invalid user field values

Iterable shows you the number of rows with invalid fields and which values are incorrect.

You can still create a list using a CSV file with values that don't match the data types of existing user fields. However, users with non-matching user field values are not added to the list or created within your project. Only users with correct values are added to the list and created if they don't already exist.

Users who do not meet Iterable's email validation requirements are not imported.

# Understanding how users are engaging with messaging

If you're curious about how your lists are performing, check out
Audience Insights.