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.
Based on their ease of use, reliability, available support by clients we recommend our data upload solutions in the following order:
- SFTP - The most reliable and the easiest to implement.
- API - Offers advanced capabilities (For more information, see the Emarsys API documentation.), and speed, but the implementation requires more technical expertise from you.
- WebDAV
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 contact 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.
Requesting SFTP/FTPS
Emarsys has Contact SFTP and Relational SFTP. Both SFTP servers have the same IP address and identical login method, but they need different SSH keys and usernames. For more information, see Uploading your contact data.
You need to raise a support ticket to have access to the Emarsys SFTP server.
To request the use of SFTP server from Emarsys, you need to obtain the following:
- Generate your OpenSSH RSA public key, for example by using PUTTYgen.
Once the SSH key is created ensure to use the OpenSSH key format. Confirm that the text in the SSH key starts with: "ssh-rsa". If the text in the SSH key starts with "BEGIN SSH2 PUBLIC KEY", it is in wrong format. - Set up a Key ring in the your Emarsys platform account and use the IP address 10.50.2.1 for importing data into Suite (if importing is needed).
You can set this up under Management → Security Settings → open Keyring tab and click Create Key. For more information, see Creating the key. - Ask your access (user account and user privileges) from Emarsys Support.
You need to attach your public key to the requesting ticket. - Emarsys provides you a user directory to store your data.
- You access an Emarsys-hosted SFTP server:
- URL: sftp://suitesftp.emarsys.net
- Port: 22
Tip: Alternatively, you can connect to 185.4.123.100, as well.
To minimize loading time use smaller data files. File size limit for Contact SFTP uploads is 10GB. Relational data SFTP has 80GB file size limit.
Transferring data via SFTP/FTPS
If you have an existing SFTP/FTPS server that you use, then you can link that remote server to transfer files to and from Emarsys. To use your SFTP/FTPS server, you need to configure the following details on the Emarsys Platform:
- remote server path
- Login
- Password
- The directory to use
You can set this up under Contacts → Data Import → Auto-imports → Create Auto-import.
To find out more about contact data imports and exports, see the following articles:
Transferring data via WebDAV
Although uploading single files larger than 1GB is possible with WebDAV, it is highly recommended to keep the size of the uploaded files below 1GB. Repeated uploads larger than 1GB can quickly use up the temporary space for processing, resulting in failed uploads.
We regard WebDAV storage as the least secure and least desirable of our data transfer methods, 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 to Management, Security Settings page (this functionality is only available to Account Owners). Proceed as follows:
- Create your WebDAV user and give it a username.
- 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.
The WebDAV protocol is not recommended for new implementations as it is considered a legacy solution by now. Its support by the IETF is expected to be limited.
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.
- Change Profile form – Allows existing contacts to change their properties in your Emarsys database.