In order to ensure that data transferred in and out of Emarsys is matched to the right contact and stored in the right format, you will need to ensure that your database fields are correctly set up.
In addition to this, you can choose from a number of available transfer protocols to match your own resources and business needs.
Contents
Emarsys Data Fields
All data transfer in and out of Emarsys is conducted using Emarsys data fields. There are a variety of options available, from manual through to fully automated imports and exports.
Whichever method you use, it is very important to ensure that the fields being imported also exist in the Emarsys application, with the correct names and field types, so that the data can transfer correctly. It is also important to specify one field as the unique identifier, which will ensure that the right data is matched to the right person. In many cases, the field email address can serve as the unique identifier. However, since Emarsys Predict and many third-party applications look for the field externalId we recommend that you create a short text field with this name and use it in all your data transfers.
When you update contact properties in the Emarsys application, the following rules apply:
- Single-choice and free text fields which contain values will overwrite any existing value.
- Multiple-choice fields will overwrite all values every time. In other words, existing values will be deleted if they are not included in every update.
- Fields with no values will remain unaffected.
- If you want to overwrite a value with an empty string, you must therefore explicitly define a NULL value for that field.
All contacts fields can also be manually edited in the Contact Properties page. For more information, see:
Whenever data is imported into Emarsys, the new values will always replace the existing ones. It is important to remember this in case you have more than one method of updating contact data, since automatic updates could result in manual updates being overwritten.
Transfer Protocols
Using the Emarsys API to transfer data
For optimum performance and high-volume data transfer, we recommend using the Emarsys API – although it does require you to have some technical resources to integrate it with your application(s).
New contacts can be created and the properties of existing contacts updated, either singly or in batches of up to 10,000 (a typical batch call to create 10,000 new contacts via the API will take around one minute). Contact lists can also be managed through the API, and transactional or batch emails triggered following the data import.
No files are involved and no external storage is required for API imports as the contact data is stored in the API call in JSON (JavaScript Object Notation).
The API can also export new registrations from the Emarsys application, as well as entire contact lists or changes to contact properties which occurred over a given time range. These are delivered in CSV format to the specified external storage (e.g. SFTP, WebDAV).
For email responses, the entire response summary of an email campaign can be called (and, for example, inserted into a table in another application). Alternatively, a file can be exported containing all the contacts (and any properties defined) who responded to emails within a given time range.
For more information, see the Emarsys API documentation.
Transferring data via WebDAV
We regard WebDAV storage as the least secure and least desirable transfer protocol, but recognize that not all companies have the technical resources to implement our API. Therefore we can set up a WebDAV folder for you, which allows you to automate your data imports and exports.
WebDAV uses the HTTPS protocol, which means that it does not need to have exceptions added to firewalls to work, so you can start using it faster.
To set up your WebDAV, go the Admin menu, Security Settings page (this functionality is only available to Account Owners). Proceed as follows:
- Create your WebDAV user and give it a user name.
- In the confirmation dialog you will see the WebDAV secret key (password); copy this.
- After closing the dialog you will be shown the directory to the storage.
If you lose your secret key you can create a new user and use that instead.
Using the above details you simply map in the directory as a shared folder, or use a client such as www.bitkinex.com or www.cyberduck.ch, and are then ready to start transferring files.
If you already have an SFTP server on your side, we can link this to our WebDAV for you.
Transferring data via SFTP/FTPS
If you have an existing SFTP/FTPS server that you use, then we can link it so that you can transfer files to and from Emarsys. To use your SFTP/FTPS server you just need to provide Emarsys Support with the following details, and they can then arrange for the facility to be configured for you:
- Server name
- Login
- Password
- The directory to use
Transferring data via Web Forms
The Emarsys Forms module offers simple functionality to create different kinds of forms to collect data from contacts. These forms can be used in emails, accessed via a link, or embedded directly in a web page. They are:
General registration form – Used to collect new contact details with general opt-in settings.
Newsletter registration form – Used to collect subscriptions for a specific newsletter only. Contacts registered by this form will not automatically be eligible to receive any other emails from you.
- Change profile form – Allows existing contacts to change their properties in your Emarsys database.