Skip to main content
Import contacts

Learn how to import contact lists to your account

Marcus Warren avatar
Written by Marcus Warren
Updated over a week ago

FAQs before your first import

  • We recommend you read about segmentation best practices before importing your list.

  • Use a .CSV file format (XLS won't work) that includes a header row (first row) with field names. The file can't have blank rows or columns on the top or on the left. View example.

  • Be sure to assign at least one tag or subscription during the import process so you can easily segment your contacts later and send them emails based on their interests.

  • Contacts will be merged by email address if they already exist in your database.

  • Existing contacts who had previously unsubscribed will remain unsubscribed after any import. You can't accidentally resubscribe them by reimporting lists.

Watch the video below for a brief overview of importing contacts:

List file format

Prepare your import file in Excel or Google Sheets or export it from another source.

  • The file needs to be saved in a CSV format.

  • Each column in the file needs to include a header in the first row to indicate the name of each field, for example Email, First name, City

  • The labels in the header row cannot contain line breaks

  • There shouldn't be a blank column on the left or a blank row on the top.

At a minimum your file must include an email field, however, we recommend you also include additional fields that you can use for personalizing email messages. For example, importing "first name" will allow you to add a personalized salutation or merge this or other imported fields into the body of your messages.

Duplicates and existing contacts fields

If your import file contains duplicate records they will be automatically merged based on the email address. If your file contains records that are already in your Envoke database then imported fields will be updated for the existing contact records.

It's possible to use an external ID as a key field instead of the email address. This is an advanced setting, please contact support for more details.

Importing unsubscribed contacts

You can bring over unsubscribed contacts into your Envoke account. You need to import these unsubscribed contacts in a separate CSV file, not mixed with other (subscribed) contacts. During the import process you will have the option to mark them as unsubscribed in Step 3. This way they will be added as unsubscribed contacts.

Field updates

Fields for existing contacts are overwritten when contacts are re-imported, except for blank values. Fields are only updated, not deleted.

Tag and subscription assignments are cumulative. New tags and subscriptions are appended to records but never removed.

List sync

By default contacts are only added to your database during the import process. You can use the list sync option if you want to automatically delete contacts that don't exist on the current CSV file. Learn more.


Upload your list file from the import page, then follow the on-screen prompts.

STEP 1: Preview

On the import settings page you'll see a preview of the list. This provides you with a way to confirm the fields aren’t misaligned or scrambled. If the preview looks good you can continue to the next step, otherwise the file format needs to be fixed first.

STEP 2: Field mapping

Map fields from your file to the corresponding field in Envoke. You can also use the “Skip this field” option to exclude a field from the import.

STEP 3: Assigning tags, subscriptions and consent

Option 1: Assign all contacts you are about to import to one or more tags or subscriptions. This way everyone on the list will be assigned the same tag or subscription.

Option 2: Tags and subscriptions are indicated in a column in the import file. Each contact can have potentially different tags and subscriptions. Tag and subscription names must be separated by commas or semicolons.

Watch this explainer video to import contacts where tags or subscriptions are assigned in your import file:

Consent status

As the last step of importing your list, select consent status to indicate your relationship with the contacts you're importing.

Import processing

After you click the Import button your file will be queued for importing. Importing generally takes only a few minutes.

You can track the status of your import from the imported files page. See the Status column for details. This page doesn't refresh automatically, click your browser's refresh button to update the status message.

You can click the number under the Contacts column to view a list of contacts who were imported. You can make changes to these contacts in bulk (for example to add or remove a tag or subscription or to change consent settings)


Original consent date

This is an optional field and applies only to contacts with implied consent that expires. You may include a field in your import field with the original consent acquisition date using a YYYY-MM-DD format and map this to the "Consent effective date" field. This way expiry of consent will be tracked from this date rather than the date of the import.

Map your original consent date to the "Consent effective date" field:

Manual review

For security reasons and to maintain good deliverability across the system, import requests from new users may be flagged for manual review by Envoke staff. Manual review can take up 2 business days.

Rejected records

Contacts that didn't get imported due to an error (for example a syntax error in the email field) are saved in a separate file for your review. The words "rejected_records" is appended to your original file so if your original file is called "January List.csv" then any rejected contacts from this file are saved in a file called "January List - rejected_records.csv". You can download this file from the secure files folder.

Country field

If you're importing a country field, you must use ISO country codes and names. All other data in the country field will be rejected.

Language field

The language field needs to use the following values:

en or English

fr or French

es or Spanish

ar or Arabic

zh or Chinese

de or German

it or Italian

ja or Japanese

ko or Korean

pt or Portuguese

ru or Russian

All other values will be mapped with language = "other".

Consent changes for existing contacts

Existing contacts with express consent will retain their "express consent" setting and won't be "downgraded" to implied consent status.

Existing contacts with revoked consent (unsubscribed contacts) will retain the unsubscribe status and won't be re-subscribed if they are re-imported.

CSV file formatting errors and troubleshooting

Envoke doesn't make modifications to the uploaded CSV file and we aren't able to assist in correcting formatting errors as these are happening on your end when the list is being exported / downloaded. You may have to enlist your internal IT person/team to help with troubleshooting.

A common error is when apps - Excel is the main culprit but not the only one - create corrupt files with invisible formatting issues, often related to encoding. These invalid characters may look like a space or a � or a similar special character.

Google Sheets is our recommended list management / spreadsheet tool. It tends to show special characters that are not visible in Excel. We suggest you open the file in Google Sheets and check for extra characters, especially in the email fields.

Did this answer your question?