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

# User data considerations

User data is imported to Iterable using the Comma-Separated Value (CSV) data format. Before you import a CSV file to Iterable, 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 rows of user data. If you have more than two million users to add/update, split them into multiple files and upload each file separately.

# Creating a new blank list

If you want to create a list without importing any user data, create a blank list. Blank lists start off empty but can be populated with users later when events add users to the list. For example, you could track which users have passed through a certain path in a journey by setting up a List Membership journey tile that adds users to a specified blank list.

To create a new blank list:

1. Go to Audience > Lists.

2. Click New List, and select the Blank List option.

3. Give the list a name and optional description, and select what type of list to create: static, suppression, or internal.

   To learn about the different list types and their uses, see Lists Overview.

4. Click Create List.

Alternatively, you can create a new blank list by making a successful call to the POST /api/lists API endpoint and including a list name and description in the payload.

# Importing users to a new list

To create a new list and import user data at the same time:

1. Go to Audience > Lists.

2. Click New List, and select the Import Users option.

3. Give the list a name and optional description, and select what type of list to create: static, suppression, or internal.

   To learn about the different list types and their uses, see Lists Overview.

4. Select CSV File Upload to attach an existing CSV file from your device or CSV Text Input to copy and paste comma-separated user data values into the text input box.

   The data requirements for list imports vary by project type. CSV imports for an email-based project must contain an email column, imports for a userID-based project must contain a userId column, and hybrid projects must contain either email or userId but can contain both (userId takes precedence when both are included).

   IMPORTANT

   Column names cannot contain special characters. Using special characters in a column name causes errors uploading users.

5. Under List Settings, choose which options to enable:

   • Only update existing users and ignore any new users: Any new users that are included in the list import are skipped. Iterable updates existing users in the project and doesn't create any new user profiles.

   • Trigger journey entries and exits with this import: When this setting is enabled for an import:

     • Users who are added to the list

       • Enter any journeys that are configured with the Subscribe to List entry source for the associated list.

       • Exit any journeys configured with exit rules that include the Subscribe to User List condition for the associated list.

     • Users whose profiles are updated with the import

       • Enter any journeys configured with the User Profile Update entry source for the associated user profile field.

       • Exit any journeys whose exit rules include the Property Changes condition for the associated user profile field.

6. Under Preview, you'll see the first 12 rows of the data you have queued for import. Before processing the import, make sure that all field names are spelled and cased correctly. Once uploaded, you cannot change a field's spelling or casing—typographical errors and inconsistent casing can lead to the creation of duplicate fields that cause data retrieval errors.

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

   The Review screen shows the new user fields that will be added to your Iterable project during your CSV upload ("Added Fields"), as well as fields that were included in the CSV data but won't be added to your Iterable project ("Dropped Fields"). Fields can be dropped from a CSV upload for a couple of reasons:

   • Your account doesn't have permission to add new user data fields.

   • 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, see Data Schema Management Overview.

   Unless set in a specific format, new user fields are set as strings by default. You can set three data types during the list import flow: 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.

8. 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 your upload is unsuccessful, see the Tips and Best Practices section for troubleshooting help.

# Creating a new list of existing users

Sometimes you may want to organize groups of users that have already been imported to your project (for whom user profiles have already been created) into lists based on shared characteristics or behaviors, but you don't need to add or update any user profile data. In this case, you can use Iterable's Segmentation tool to find and save groups of similar users.

There are several options for saving the results of a segmentation query.

Save as:

• Static list
• Dynamic list
• Scheduled list (Beta—only for queries that use the Matches Catalog Data comparator)

Export as:

• CSV file
• Facebook Custom Audience
• Google Ads Audience

To create a list of existing users using Iterable's Segmentation tool:

1. Go to Audience > Segmentation.

2. Create a segmentation query that defines the set of user characteristics or behaviors you're interested in. For more details on how to do this, see Creating a Segmentation Query.

3. Once you have the results of the segmentation query, click Save As to choose how to save the resulting group of users. You can save as a static or dynamic list for sending or suppressing campaigns, download a CSV file to your device, or export the segment to Facebook or Google Ads if your project has these integrations configured.

4. If your segmentation query includes catalog data, you can also save the results as a scheduled list. To learn more about creating scheduled lists, see Working with Scheduled Lists.

# Saving a segment as a static list

To save a one-time snapshot of users who fit the criteria of a segmentation query, save your results as a static list.

When you save the results of a segmentation query as a static list, the query that defined the list is not saved—only the resulting list of users. This means you can't edit the query and regenerate the list later. If you need to edit and refresh the query results over time, save the list as a dynamic list instead.

To save query results as a static list:

1. Click View Results to fetch the current group of users who match your defined eligibility criteria.

2. Click Save As > Static List.

3. Enter a name and description for the list.

4. (Optional) Set a maximum list size. For example, if your search results exceed the list size limit of 5 million users, you could enter "5000000" to cap the size of the list.

5. (Optional) Click Split Into Another List to split your search results into more than one list. For example, if your search results exceed the list size limit of 5 million users, you could split the results into two lists, each with a list size of 2500000. Users are assigned randomly to each list split until the defined maximum size is reached.

6. Click Save List.

# Considerations for creating static lists using the Segmentation tool

When you use the Segmentation tool to create a static list, there is a list size limit of 5 million users. To avoid hitting this limit, you can create a list from the Lists page (size limit 2 GB) or use the POST /api/lists/subscribe API endpoint.

# Saving a segment as a dynamic list

To continually refresh the group of users that matches your defined segmentation criteria, save the segment as a dynamic list.

When you save a segment as a dynamic list, the segmentation query is also saved. This means that you can adjust your query criteria as needed over time to refine the group of users that matches your desired criteria.

When you choose a dynamic list as the audience for a campaign, at send time, Iterable fetches the latest batch of matching users as recipients.

To save query results as a dynamic list:

1. Click View Results to fetch the current group of users who match your defined eligibility criteria.

2. Click Save As > Dynamic List.

3. Enter a name and optional description for your list.

4. Click Save List.

# Saving a segment as a scheduled list (Beta)

Scheduled lists are designed for queries that match users with catalog data. While dynamic lists refresh at send time, scheduled lists recalculate membership once every 24 hours at a time you choose. During each refresh, Iterable updates the list to reflect the current batch of users who meet your catalog segmentation criteria.

Scheduled lists can be used anywhere you use lists in Iterable. They’re useful for recurring campaigns that depend on changing catalog data, such as weekly promotions, back-in-stock alerts, and subscription reminders.

To learn how to create and use scheduled lists, see Working with Scheduled Lists.

# Exporting a segment

Sometimes you may want to save a segment in order to use it outside of Iterable. To do this, you can export the segment to a CSV file or to one of Iterable's supported integrations with Facebook and Google Ads.

1. Click View Results to fetch the current group of users who match your defined eligibility criteria.

2. Click Save As.

3. Under Export As, select whether you want to export the results as a CSV file, a Facebook Custom Audience, or a Google Ads audience.

   NOTE

   To export segments as Facebook and Google Ads audiences, these integrations must be configured for your project.

   • CSV file – Select which fields to include in the exported file, then click Export.

   • Facebook Custom Audience – Select your Facebook Ad account ID, give your audience a name and description, and click Export.

   • Google Ads Audience – Select your Google Ads account ID, give your audience a name and description, and click Export.

# Updating list membership

After a static list has been created, you can update it as often as necessary by running additional CSV file imports. Each additional CSV upload to an existing static list can make the following updates:

• Subscribe new users to the list: Creates user profiles for users not previously imported to your Iterable project and generates an emailSubscribe event in their event history.

• Update the user profile data of existing users: When user data fields are added and/or the values of existing fields are updated, Iterable updates the user profile to reflect the changes.

To update an existing static list:

1. Go to Audience > Lists.

2. Find the list you want to update, and click its overflow menu (three dots).

3. Select the Update option. This opens the CSV import menu.

4. (Optional) Edit the list's name and description if necessary.

5. Upload the updated CSV file.

6. (Optional) Enable the Trigger journey entries and exits with this import option. If enabled:

   • Users who are added to the list

     • Enter any journeys that are configured with the Subscribe to List entry source for the associated list.

     • Exit any journeys configured with exit rules that include the Subscribe to User List condition for the associated list.

   • Users whose profiles are updated with the import

     • Enter any journeys configured with the User Profile Update entry source for the associated user profile field.

     • Exit any journeys whose exit rules include the Property Changes condition for the associated user profile field.

7. Click Review.

8. Review the summary of your queued list import. When you're ready to submit the list update, click Import List.

# Removing users from lists

You can automate list membership updates (subscribes and unsubscribes) with journey List Membership tiles.

To remove users from a list via CSV upload:

1. Go to Audience > Lists and locate the list from which you want to remove subscribers.

2. Click the list's overflow menu (three dots), and select Unsubscribe. This opens the CSV import menu.

3. Upload a CSV file or enter the CSV data of the users that you want to remove from the list.

4. Click Review.

5. Click Remove Subscribers.

The designated users are unsubscribed from the list, and an emailUnSubscribe event is logged to their user profiles. Users included in the CSV upload who aren't subscribed to the list at the time of the unsubscribe operation are ignored.

Alternatively, you can remove users from an existing static list by calling the POST /api/lists/unsubscribe API endpoint and including the list ID and user identifier(s) in the request body.

You can also remove a user from any lists they're subscribed to from their User Profile page. To do this:

1. Go to Audience > User Lookup.

2. Click Lists and find the list you want to unsubscribe the user from.

3. Click the overflow menu (three dots), and select Remove from List.

# Subscribing and unsubscribing users from message channels

In addition to subscribing and unsubscribing users from individual lists, you can subscribe and unsubscribe users from overall message channels.

1. From the Lists page, click the overflow menu (three dots) at the top of the page.

2. Under Manage Users, click Subscribe to Channel or Unsubscribe from Channel. This opens the CSV upload menu.

3. Select the channel(s) you want to subscribe users to or unsubscribe users from.

4. (Optional) Enable the Trigger journey entries and exits with this import option. If enabled, users included in the import:

   Subscribe to Channel Imports

   • Enter any journeys configured with the Subscribe to Channel entry source associated with your selected channel(s).

   • Exit any journeys configured with Subscribe to Channel exit rules associated with your selected channel(s).

   Unsubscribe from Channel Imports

   • Enter any journeys configured with the Unsubscribe from Channel entry source associated with your selected channel(s).

   • Exit any journeys configured with Unsubscribe from Channel exit rules associated with your selected channel(s).

5. Upload or enter your CSV data.

6. Click Subscribe Users or Unsubscribe Users, depending on the action selected.

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

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Segmentation and Lists

Support docs

• Lists Overview
• Managing Lists
• Segmentation Overview
• CSV List Import Best Practices
• Using Audience Insights to Understand Your Users
• Choosing an Audience for a Blast Campaign
• Subscribe and Unsubscribe Events