Overview
Before you are able to start sending messages, you will need to import your contacts. While you are able to add contacts one at a time, you will most likely be importing them using a CSV file.
Before importing, it's recommended to perform some list hygiene best practices to help maintain healthy deliverability. We have provided some info and recommended vendors in our article: Data Validation/Hygiene Vendors and Tips.
Read on for a step by step guide on importing your contacts or watch the following video for a complete walkthrough.
Importing Contacts Video
Create the contact attributes
Before importing any contacts, it is important to create their associated attributes first. You can create these during importing, but it is not recommended when you have a large number of attributes to create. To learn more, read the article about creating contact attributes.
Create the list attributes
Before importing any contacts, it is important to create their associated lists first. You can create these during importing, but it is not recommended when you have a large number of lists to create. To learn more, read the article about creating lists.
Create your data file
A data file may include an unlimited number of contact records with each contact record containing an unlimited number of attributes and list values.
Cordial has one master database that includes all contacts, their attributes and list associations. There are not separate lists in Cordial, rather a contact's list association is reflected by a list attribute value being true or false (1 or 0 in the data file).
The most common scenario for loading a data file is uploading a file from your computer. However, you also have the option to load the file from any HTTP/HTTPS, FTP, SFTP or S3 location. An additional option for Google Cloud Storage will be available once you've completed the Google Cloud Storage integration setup. The following data file formats are supported when importing a local file from your computer:
- TSV - tab-separated values
- CSV - comma-separated values
- TXT - a text file
The most common file format is a CSV or comma-separated values file, where the comma character acts as the delimiter between fields. If you are creating or manipulating your file in a program like Microsoft Excel, simply save your file in a CSV format using Excel's Save As feature and select CSV (comma delimited).
In your data file, create a column header so you can match up your data values with the appropriate Cordial attribute or list value. This will be important when you import the file and want to be certain you are loading the data correctly.
For example, if you had a file that contained email address, first name and last name for each contact and you wanted to include them on the lists newsletter and weekly_specials, your data file would need to look like the following:
In table format:

In CSV format:
channels.email.address,first_name,last_name,newsletter,weekly_specials fredgarvin@example.com,Fred,Garvin,1,0 arnoldbabar@example.com,Arnold,Babar,1,1
The values for each contact's list association are denoted by a boolean value where a 1=true (on the list) or 0=false (not on the list).
For email address, be sure to use the key channels.email.address in order to map correctly into the system when importing.
Subscribe status management
You can update contacts' subscribe status using the channels.email.subscribeStatus column header in your import file. Under this header, assign one of three possible subscribe status parameters for each contact: none
, subscribed
and unsubscribed
.
- Once a contact's subscribe status is set to
unsubscribed
in the Cordial platform, it is not possible to change this status using the UI contact upload file. However, the unsubscribed status can be changed via the contact imports API endpoint or by accessing the individual contact's profile in the platform and manually changing the subscribe status. This is intended as a precautionary measure to prevent accidental subscription modifications to previously unsubscribed contacts. - If your import file does not contain instructions for handling contacts' subscribe status, and it contains contacts whose current subscribe status in the Cordial platform is
none
, their status will automatically be changed tosubscribed
. To avoid this automatic assignment, always include the channels.email.subscribeStatus header in your import file and designate the appropriate subscribe status parameter for each contact.
Adding geo attributes
When importing geo field attributes, use the key that you created (hm_address, work_address, etc.) appended with the Cordial standard field name in dot notation.
Available standard fields are:
- street_address
- street_address2
- city
- state
- postal_code
- country
- tz (time zone)
- loc
- lat (latitude)
- lon (longitude)
For example, if we created a geo field called hm_address we would write each geo field as:
- hm_address.street_address
- hm_address.street_address2
- hm_address.city
- hm_address.state
- hm_address.postal_code
- hm_address.country
Your CSV file would look like the following:

Adding arrays
In addition to strings, numbers, dates and geo attributes, Cordial also supports uploading arrays of comma separated values within a contact attribute.
For example, you might have an array of values for a contact attribute called favorite_fruits. Because array values are separated by commas, they need to be escaped by double quotes to avoid errors while uploading a CSV file.
Your data file might look like the following:
In table format:

In CSV format:
channels.email.address,favorite_fruits fredgarvin@example.com,"[""apple"",""orange"",""pear""]"
Adding and removing array items
The above example will replace any array items that currently exist in the array attribute.
To add an item to an existing array attribute use the following code:
channels.email.address,favorite_fruits fredgarvin@example.com,{ "add": ["apple"] }
Alternately, if your CSV elements already contain quotes (as some applications may export) use the following syntax:
"channels.email.address","favorite_fruits" "fredgarvin@example.com","{ ""add"": [""apple""] }"
You can also add multiple items to the array:
channels.email.address,favorite_fruits fredgarvin@example.com,"{ ""add"": [""berry"",""kiwi""] }"
To remove items from the array:
channels.email.address,favorite_fruits fredgarvin@example.com,{ "remove": ["apple"] }
Upload and import the data file
Once the data file is prepared, navigate to Contacts › Import Contacts

Click the New button and fill out the form.

- Import Source - select whether the source is a local file or hosted remotely.
- Header Row - select if your data file has a header row. The use of header row is recommended to make it easier to match the columns with their corresponding attributes when importing.
- Choose Delimiter - specify delimiter type.
Follow the prompts to upload the file and then map each column of the data file to the appropriate attribute.

For attributes and lists that already exist in the system with the same name as the header column, they should be automatically mapped.
For attributes that have a different name than the header column, use the dropdown labeled Choose to map to a previously created attribute in the system.
To create new attributes and lists, click + Attribute or + List to add a new one and map it accordingly.
You can also select the ignore checkbox to ignore the column entirely.
After mapping the appropriate fields, click continue and complete the import options.

Give the import a name and description (optional). The import name may only contain letters, numbers and dashes.
Select one of the import options:
- Import all contacts - insert new contacts and update existing contacts.
- Ignore new contacts - only update existing contacts.
- Ignore existing contacts - only insert new contacts.
Choose whether or not to suppress message triggers:
- True - do not send message though event trigger meets condition.
- False - send message if event trigger meets condition.
Choose whether or not to send an email notification when import is complete.
Click the Submit button to start the import.
You will be taken to the Jobs page where you can view the status of all import jobs.
Verify upload was imported without errors
To verify that the import was created without errors, hover over the arrow in the import row to see the details of the import job. If any contacts were rejected, you will have the option to download a list of these records. This file will show the line of the rejected record and an error message.

You can access the Jobs page at any time by clicking the icon in the header bar of the application.
Importing Contacts on a Recurring Schedule
You have the option of importing contacts on a recurring schedule.
- Navigate to Contacts › Import Contacts or Data › Data Automations › Import Contacts
- For Import Source, choose HTTP/HTTPS, FTP, SFTP, S3 Amazon or Google Cloud.
- For Schedule, choose Import on a recurring interval.
Tip: Public key authentication can be used when the import source is SFTP.
- For Source URL, enter the URL path for the data file.
The input field supports Smarty so you are able to use Smarty variables in the URL path. For example, you could name your data file with the desired import date (contacts_2020_09_14_09.csv) and then use Smarty to render the current date in the Source URL at the time of import: contacts_{$utils->getNow('America/Los_Angeles', 'Y_m_d_H')}. This example uses the $utils.getNow utility so that the import is deployed according to the account timezone. If $smarty.now is used the time will be UTC. Learn more about date and timestamp variables.
- Set the Schedule Interval to the desired interval.
- Select the Start Date and optional End Date and click Continue.
- Map the data file to the contact attributes.
Note:
- No data will be imported during data mapping.
- If you schedule an import for a future date you will still need to map the data with a file that is immediately available on the designated server source.
- After data mapping you will be taken to the Data Automations page where you can view, disable/enable or remove a scheduled import.
Import Contacts Via the API
You also have the option to import contacts via the API. Please read the article about importing contacts via the API to learn more.
Adding a Contact via JavaScript
Contacts can also be added via JavaScript listeners that reside on your website.
Learn more about JavaScript listeners.
In the next article learn how to export contacts.
Comments
0 comments
Please sign in to leave a comment.