Using the List Importer

Which column headers to use

Every column in your file needs a header in its first row. The header tells ShortStack which field the column goes into.

Your column holds	Header to use	Example
A standard field, such as email or first name	The standard header from the table below	email
A field you want to create, such as a store preference	The field type, an underscore and a label, with no spaces or special characters	text_myfield
A field already in your Field Library	The field's existing name	custom_boolean_3

Before you start

• The List Importer is included on the Enterprise plan. See Enterprise on the pricing page.
• Each import creates a new list. You can't add to an existing list.
• Only import people who opted in. You'll confirm that everyone subscribed to your email marketing, and that any EU contacts were collected with double opt-in.
• Start from the template. Download the import template. It has every standard header and two custom field examples.

Prepare your file

1. Open the template, or your own spreadsheet.
2. Put one kind of data in each column. For example, split a full name into a first_name column and a last_name column.
3. Give each column a header from Standard headers or Custom field headers. Delete any template columns you don't need.
4. For checkboxes, enter true or 1 for yes, and false or 0 for no.
5. Save the file as a .csv file. Other file types can't be imported.

Standard headers

Header	What it holds
email	Email address
first_name	First name
last_name	Last name
address_1, address_2	Address
city, province, postal_code, country	Location
agree, approved	Checkboxes: true or 1, false or 0
phone, age	Phone number and age
votes1, votes2, votes3	Votes for each voting round
entry_title, entry_description	Entry title and description
created_at	When the entry was created
category	Category
post_url	Upload field

Custom field headers

To create a new custom field, write the field type, an underscore, then a label. Use no spaces or special characters in the label.

Header	What it creates
boolean_mylabel	A checkbox field named "mylabel"
text_myfield	A text field named "myfield"

To fill a custom field you already have, use its existing name from the Field Library, such as custom_boolean_3.

Import your list

1. Open the Lists Manager and click Import List at the top right.
2. Name the list, add any tags, and click Next.
3. Choose your .csv file and click Next.
4. Tick both confirmations: that the list only includes subscribed contacts who opted in to your email marketing, and that any EU contacts were collected with double opt-in.
5. Click Submit.

What happens next

The file is imported in the background. You'll get a notification in ShortStack when it's finished, or if there's an error, with details of what went wrong.

When it's finished, find the new list in the Lists Manager by its name or tags. You can use it like any other list, such as to send emails or view its entries.

If something goes wrong

What you see	What to do
There's no Import List button	The List Importer is included on the Enterprise plan. On other plans, entries come in through your campaigns' forms or a social import.
You get an error notification	Read the details in the notification, fix the file, and import it again.
A column didn't come through	Check its header matches one in Standard headers exactly, or follows the custom field format.
Names or addresses came through in one field	Split them into separate columns, such as first_name and last_name, and import again.
Checkboxes show the wrong value	Use true or 1 for yes, and false or 0 for no.
The file won't upload	Save it as a .csv file. Excel and Numbers files can't be imported directly.

FAQs

Can I import contacts into an existing list?

No. Each import creates a new list, which you name and tag as part of the import.

Which plan includes the List Importer?

The Enterprise plan. On other plans, entries come in through your campaigns' forms or a social import. See Enterprise on the pricing page.

Can I import people who haven't opted in to my emails?

No. Before you submit, you confirm that the list includes only subscribed contacts who opted in to your email marketing, and that any EU contacts were collected with double opt-in.

Can I upload an Excel file?

Not directly. The List Importer accepts .csv files only. In Excel or Google Sheets, save or download the sheet as a .csv file first.

Related resources

• Lists Manager
• Field Library
• Entries API
• Import template (.csv)
• How to configure a list field (video)