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

Here are some things to know before you begin this process.

• If you've already started an import, learn how to review and edit your audience fields or troubleshoot your import.
• The only fields that Mailchimp requires are the email address field for email contacts, and the SMS phone number field for SMS contacts. 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

The email address field is required for email contacts. When you import email contacts, you must include an email address column in your import file and only 1 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 features like segmentation. 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 try to recognize countries by name, but it increases the likelihood of error.

• A United Kingdom address with UK as the country won't 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 US phone numbers, choose the (###) ###-#### format on the Audience field and merge tags page. If you are importing SMS contacts into your audience, use the SMS phone number field instead.

SMS phone number

The SMS phone number field is required for SMS contacts. This field is specific to Mailchimp’s SMS Marketing, and it’s different from the phone number field. Use the SMS phone number field to import SMS contacts who have opted into your SMS marketing. You can only import SMS contacts from your sending country.

In your SMS Marketing program, format SMS phone numbers based on the sending country. SMS phone numbers imported into Mailchimp must be in the E.164 format. Phone numbers that follow the E.164 format include the following:

• Must begin with a + sign
• Have a 1–3 digit country code
• Subscriber number: includes area code, up to 12 digits.

To learn more about how to import SMS contacts into your audience, check out Import SMS Marketing Contacts to Mailchimp.

At this time, the SMS phone number field isn’t supported with the Mailchimp Marketing API.

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 ZIP codes, use an additional text field. Zip code fields are limited to five digits.

Certain features, like 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. This field shouldn’t be used for phone numbers.

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.

To do this, you’ll need to import your contacts' birth month and day information into a birthday field instead of a regular date field. We'll accept a field with a month-day (MM/DD) or day-month (DD-MM) format.

Image

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

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

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.

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.

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