Table of Contents:

How to import contacts and their accompanying data-points into a list

For an introduction to this topic we recommend visiting the Import Your Contacts section in our Getting Started Guide

  • Go To List → Import

  • Click on the 'Add File' button to browse to the CSV file you want to import. It is strongly recommend that to download the sample CSV file for your convenience as well as to prevent errors when importing it into the list.

    Note: if you choose the 'Email me when done' option, it will send an email message to the 'Notification Email' indicated in the Account Profile page. 

  • The column headers of the CSV file you're using to import, MUST match the field names as they are in your List > Fields Setup:

What to watch out for when importing

  • (warning) The import file must contain at least one column containing the email addresses.
  • (warning) The column headers of the file that you import MUST match the names of the fields exactly as they are in your List in Ongage.
  • (warning)  When uploading date fields, make sure the date format (e.g., dd-mm-yyyy) you're importing matches exactly the format you set for that field, in the field setup (List > Fields Setup). Also note if you try to upload a date and time-stamp to a field that only was set to accept a date without a time-stamp – you might have trouble with the date field getting properly populated.

How long do imports take

  • Following the August-22 release of faster import speeds for large imports files – Ongage takes large import files, and behind the scene splits the import file into two parallel imports, taking advantage of computer parallel processing, and thus doubling import throughput, and cutting large import times in 1/2 and even better. Following are the benchmarks before and after this improvement.      
Import SizeAvg. Time in Hrs BeforeAvg. Time in Hrs After
500K – 1M    1.611.33
1 – 5M


5M – 10M 10.135.82
10M – 20M12.25.73
  • You may track the progress of the file upload from within the List→Import screen. When the Status changes to 'Completed' indicates that the import of the entire file has completed.

What is the Max Size of an Import File

  • The current default max size of an import file is 500 MB. Depending on how much data might be in each column row, the max number of rows will vary. That max size can be increased to 1GB depending on the pack size and in coordination with your account manager. 

How to use the "download CSV sample file"

  • To eliminate errors, it is highly recommended that you first download the CSV sample file. You may find the link to that file from within the 'Import Data' interface. The sample file will include all the Dynamic Fields you have defined to this point as headers. Make sure to update the file with your content, while matching the actual content to the file headers

What are the different types of import failures: duplicate, existing, incomplete, invalid

In general: Total = Success + Failed.

  • Duplicate – duplicate email addresses within the import file itself. 
  • Existing – some or all of the emails you're attempting to import already exist in this List.
  • Incomplete – mandatory lists fields are missing in the header of the CSV file you tried to import.
  • Invalid - email address is not valid (syntax).

If you hover with your mouse over the question mark of each failed type column you'll get the meaning for that fail type.

How do I update existing contacts in a List 

If you'd like to update the value(s) of a 1 or more list fields for a given set of existing contacts, follow these steps: 

  • Import a CSV file of the contacts you'd like to update, and check the Update existing contacts option (see following section for detailed explanation about overwrite).

  • If for example your list contains 10 fields, but you only want to update the values of one of those fields, let's say for example 'city'. Simply create a CSV file with 2 columns, one with email in column 1 and the other with 'city' in column 2, as in the following illustration:

  • (info) Note: When the check-box is not checked, the data fields of all existing contacts will not get updated, and only new contacts will get added to the list.

Overwriting an existing contact does not change it's active status

  • Updating the field values of a contact, does not change their Active/Inactive status (i.e., hard bounced, unsubscribed, complaint).
  • In other words, if you do an import of an existing contact that has previously hard bounced, unsubscribed, or complained, the import itself will not change it's active/inactive status. For the latter you'll need to go to the Contacts Manager → Change Status screen and resubscribe them in order to reactivate them.

Do not overwrite with null values - what does it mean

  • When this option is selected (which is the default), and if there are null/empty values in the CSV you are importing, then it will not overwrite existing data in the list with null/empty values.
  • So let's say you have a column in the CSV with empty/null cells, and in the list DB there are values. Those values won't be overwritten with null

Import FAQ

How do I update a single contact

Choose any one of the following 3 options:

  1. Go to List → Contact Manager, enter an email address, and click the 'Search' button, and it will open the Edit Contact Pop-up for that email address.

  2. Import a CSV file with the contact you'd like to update, and check the 'Overwrite existing contacts' option
  3. Go to List → Contact Manager and under the Search Tab,
    1. Perform a search (of a desired segment or campaign for example).
    2. Once the report is ready, in the 'View Report', will appear a row for each contact that came back in that search.
    3. Under the 'Actions' column is an 'Edit 'Contact' icon, click on it to get to the  Edit Contact Pop-up for that email address.

What is the "Set Default Values" checkbox used for

  • The 'Set Default Values' button is used to set a default value for a given field when doing an import. When you click the checkbox, a list with all of your dynamic List fields will appear. Check the field(s) you would like to assign a default value for and enter the default value(s). When you import the CSV file, the platform will use the default value you defined here wherever there is no value in the file for that field.

How to Abort an Import

(info) Note: Abort import option is not yet available for the imports done in the 'Change Status/Delete' tab under Contact Manager.

(info) Note: Imports can be aborted only if their status is one of the following :

    • Queued
    • Validating
    • Processing

This feature allows customers to abort an import done via a CSV file to prevent human errors. For now, this feature is available only for List Import in for Sending and Suppression list both.

  1. Go to List > Import and click on the “Abort” icon visible under Actions.

  2. Once the import is aborted, the status of the import file changes to aborted as displayed in the screenshot below.

(info) The abort  will stop importing more contacts. But the contacts which were imported already before the Status was changed to “aborted” will still remain imported in List. In order to Safely remove contacts which are imported before the Abort function is completed, please refer to the “How to safely remove contacts added through a mistaken import?” section below.

About the Import ID


(info) Every contact that you bulk import using a CVS file (or via the API import command) has an Import ID associated with it. You can then use this ID for segmenting all the contacts in that import. See the following section for more details.

New Accounts

(info) As of 2019 all new accounts have the System field Import ID in their Segment criterion:

  • This system field holds the last 10 import IDs for each contact. What that means is for each contact that you import over and again (e.g., in order to update it list field values), it will retain the last 10 import IDs, that you can segment on. I.e., on the 11th import, the oldest Import ID will get dropped.
  • Older accounts, prior to 2019 have also been migrated to this new Import ID, in cases where there were no segments found to be using the older 'Import Id'. Moreover, over time, support has suggested older accounts to migrated to this new Import ID.

Old Accounts

For accounts pre-dating 2019 they might have the the System field Last Import ID in their Segment criterion:

In this case only the last Import ID is retained for every contact that was successfully imported. Meaning you can make a segment based ONLY on latest import for a given contact.

(info) To be noted: many accounts pre-dating 2019 were also converted to the new method that retains the last 10 import IDs, if it was found that the account had no segments using the Last Import ID. If you'd like your account to be switched to the new method, please contact Ongage Support.