Format Guidelines for Your Import File

When you import contacts to Mailchimp, you’ll match each column in your import file to a field in your Mailchimp audience. Certain types of fields, like email address and birthday, require a specific format to import correctly.

In this article, you'll learn how to format each column in your file to get the best results when you import.

Before You Start

  • If you've already started an import, learn how to review and edit your audience fields or troubleshoot your import.
  • The only field Mailchimp requires is Email Address. Other fields are optional, but may be necessary for personalization, segmentation, or other features.
  • Clearly label each column in your import file so you can easily choose the field type during the import process. For example, if you have a column named "Contact Email Addresses," you'll know to choose the Email Address field type.
  • You can arrange the columns in your file in any order.

Email Address

You must include an email address column in your import file, and only one email for each contact. Review this column for anything that might cause syntax errors, like missing information, unsupported characters, and extra spaces before or after an address. For example, we can only support international characters like ñ or é if they come after the @ symbol.

Text

Text fields are limited to a maximum of 255 bytes of information, and will be clipped if the limit is exceeded. In many alphabets, this is equal to 255 characters. Some alphabets or symbolic characters, like emoji, use more than one byte of information per character, so it isn't always a one-to-one ratio.

Use text fields for:

  • first name and last name
  • language preferences
  • numbers without comma separators
  • additional data you want to add, like job title or company name

Address

The address field is designed to contain each contact’s complete mailing address, which can be used with postcards, segmentation, and other features. This field is automatically included when you create an audience, but is hidden from signup forms unless you choose to make it visible.

Here are some other things to know when you prepare your address field for import.

  • Include each contact’s complete address, including the zip code and country. If the address information in your file is stored in multiple columns, combine them during the import.
  • Separate each part of the address with two spaces instead of commas.
  • Each line of the address must be fewer than 45 characters.
  • Use the two-letter country code instead of the country name. Our system will attempt to recognize countries by name, but it increases the likelihood of error.
  • A United Kingdom address with UK as the country will not import correctly. You’ll need to use GB instead.

Phone

The phone field is included when you create a new audience, but is hidden from signup forms unless you choose to make it visible. It uses international format by default. If you know you’ll only have U.S. phone numbers, choose the (###) ###-#### format on the Audience field and merge tags page.

Zip Code

Use the zip code field in combination with text fields if you have U.S. address data stored in separate columns and don’t want to combine them. To store international postal codes, use an additional text field. Zip code fields are limited to five digits.

Note

Certain features, like postcards and address-based segmentation, won’t work with address data stored in separate audience fields. If the address information in your file is stored in multiple columns, we'll help you combine them when you import.

Number

Use a number field to import numbers or currency values to your audience. We'll add comma separators to large numbers like 1,000 or 1,000,000.

import-file-column-donation

Date

To import dates other than birthdays, use either the ISO Standard year-month-date format (YYYY-MM-DD) or month-day-year format (MM-DD-YYYY).

Mailchimp will attempt to convert the date field to match your account's default date format. For best results, we recommend that you use the ISO Standard format, YYYY-MM-DD.

Birthday

If you store your contacts' birthdays, you can use this information to send annual birthday automations that include special offers or friendly messages. You'll need to import this information into a birthday field instead of a regular date field. Be sure to use the ISO Standard year-month-date format (YYYY-MM-DD).

Screen Shot 2019-02-07 at 1.06.47 PM

Image

Image fields must contain the full source URL for a hosted image, which can be used to insert personalized images in campaigns.

Website

Website fields can be used to store custom links for each contact and must include the full URL.

Marketing Permissions

If you add contacts who have given GDPR-friendly consent for marketing permissions, you can import that information to Mailchimp. To match the column to a Mailchimp audience field, select Marketing Permissions for the column name. Imported permissions must match the marketing permission options you specified for this audience in your GDPR-friendly form.

Tags

Tags help you organize and label your contacts. To import tags, create a single column in your spreadsheet labeled Tags. For each contact, add all of the tags that apply to them, separated by commas.

Here are some other things to know when you prepare your tags for import.

  • If a tag doesn’t already exist in your audience, we’ll create it when you import.
  • Tag names can be 100 characters or fewer. If a tag exceeds the character limit, we’ll truncate it.
  • Emojis cannot be imported. We recommend you replace any emojis with text.
  • If a tag contains a comma, you’ll need to enclose the tag in double quotes to retain the comma. For example, the tag Monday, Wednesday should be formatted as “Monday, Wednesday”.

import-example-tags

Groups

If you plan to use groups, you can add subscribers to groups during the import process. If your audience doesn’t already include the groups in your import file, you’ll need to create them first.

In your file, label the group column to match your group category. For each contact, include their group names. To add a contact to more than one group name, separate each name with a comma and a space.

For example, if you have a Newsletter Preferences group category and the group names are Student Events, News, and Donations, format the Newsletter Preferences cell for someone in all three groups like this.

image shows Newsletter Preferences column cell that contains Students, Events, News, Donations

Download a Sample Import File

If you need help, try our sample import file as a starting point. The sample file contains columns for an import that includes email address, first name, last name, address, birthday, a custom group, and tags.

Download the sample CSV file, and replace the sample data with your subscriber data. Customize the fields to match the data you have for your audience. Follow the format guidelines for different types of information, to update your Mailchimp audience correctly.

Sample File

Click the link to download the sample CSV import file. For best results, open the file in a spreadsheet program like Microsoft Excel or Google Sheets.

Sample CSV Import File

After you update the file with your subscriber information and save it, learn how to import it into Mailchimp.

Note

The data contained in the sample import file is not actual contact data and has been created for informational purposes only. Replace the sample information before you import.


Was this article helpful?

Anything else we can do to improve our site?