This article explains how to set up an SFTP sync, which is an additional feature that must be turned on for your account.

Ⓘ Available to Plus, HQ, Essentials, Teams, and Corporate accounts

	In This Article
	What Is an SFTP Sync? Setting Up an SFTP Sync Prepare Your Field Mapping File SFTP Setup Wizard Import Settings Manage an SFTP Sync

What Is an SFTP Sync?

The SFTP sync feature is available to the account types listed above at an additional cost. It establishes a daily sync that imports contacts to your audience. The SFTP sync uses a file-sharing application called Files.com. Your site connects to a Files.com directory and uploads your contact file there on a schedule of your choosing. Once you set up the SFTP sync in your Emma account, Emma will run a daily task to pick up the file from Files.com and import it into your account.

Once the SFTP sync feature has been enabled in your account, you'll see a new tile in the Connect section of your Audience tab. However, in order to access the setup wizard, you will need to be an account Parent, Manager, or Administrator.

What is the size limit for SFTP sync files?

The size limit for SFTP sync files is 1 GB.

Setting Up an SFTP Sync

Prepare Your Field Mapping File

Before you begin, it's important to prepare your field mapping file.

⚠	Warning
	The field mapping file is not the file that you'll upload to Files.com. This file gets uploaded as part of the SFTP setup process and its sole purpose is to show Emma which fields will be in your real Files.com file and which Emma fields they should map to.

 

The field mapping file must meet the following criteria:

• Must be a CSV file
• Must be less than 25 MB
• Must contain the same column headings that your real sync file will have
• Must not contain any extraneous column headings - if you won't be mapping a field, don't include a column for it
• Should not contain any contacts, only column headings

For example, if you know that your daily sync file contains columns for "Email", "First name", "Last name", and "Favorite color", then your field mapping file should have a column heading for "Email", "First name", "Last name", "Favorite color", and nothing else.

If your field mapping file also contains a column for "Favorite food", you should delete that column from the file before uploading it. If the file that you will be uploading to Files.com contains a column for "Date of birth", but you don't plan to map it, then you should delete that field from the file - do not include it.

The best way to ensure that your sync runs as smoothly as possible is to follow these rules:

• If you don't need it, don't map it.
• If you're not mapping it, remove it from your spreadsheet.
• Keep your column headings consistent. If you mapped a column heading as "Birthday", do not change it to "Date of birth" - if you do, your sync will fail until you update the field mapping.
• The headings of your field mapping file should match the headings of your Files.com file exactly.

Once you've got your field mapping file saved and ready, proceed to the SFTP setup wizard.

SFTP Setup Wizard

1. Navigate to your Audience tab.
2. Click on the Connect section in the panel on the left.

3. Click on the Connect SFTP sync tile.

   

4. If this is your first time setting up an SFTP sync, a pop-up window will appear.
   1. Click on the OK button to set up your SFTP account credentials.
   2. The wizard will create your Files.com account and send you a welcome email with a link to log in and set up your password.
   3. Click on the link and verify your Files.com account. Be sure to share your Files.com username and password with your IT team or whoever is helping you set up your SFTP sync.
5. Return to your Emma account and click on the Next button.

6. Click on the File drop area and select your field mapping file.

   

7. Click on the Next button.
8. In the "Sync name" field, enter a name for your sync.
9. In the "File name" field, enter the name of the file that you will upload to Files.com. This is how Emma will know which file to look for in your Files.com directory. Do not use the name of the field mapping file from the previous step. You can also add a wildcard to the end of the file name if you plan to include a changing date as part of your file name. For example, Emma_Daily_File*.csv would allow you to upload a file with the name Emma_Daily_File_20240329.csv to Files.com.

10. Use the "Destination group" dropdown menu to choose the group that will be connected to the sync.

    

11. Click on the Next button.
12. Use the dropdown menus to select an Emma field for each column. The columns in your field mapping file are listed on the left and Emma fields are listed on the right.
13. Click on the Validate file button, then click on the Next button.
14. Use the "Select hour" dropdown menu to select the time of day that your sync should run. Use the checkboxes the choose your other import settings. These settings are explained in depth below.
15. Click on the Next button.
16. Review your choices on the Summary screen. Once you're satisfied, check the box to agree to the Terms of Service and click on the Activate sync button.

✎	Note
	If you have not yet uploaded a file to Files.com, the SFTP sync will probably report an error during its first sync attempt. This is expected. Your Files.com directory is empty, so there is nothing for Emma to sync. Simply upload your file to Files.com, return to Emma, and click on the Sync now button. You may need to click on View executions in order to see the Sync now button.

Import Settings

Hour of Day

When choosing a time for your sync to run, a good rule of thumb is to choose two hours after you expect your site to send your daily file to Files.com. For example, if your site will upload your file to Files.com each day at 1:00 am, then you should select 3:00 am to provide extra cushion for processing.

Remove Members vs. Delete Members

As the first step of the sync, Emma always empties the target group. However, there are two different ways that Emma can go about emptying the group. The first two checkboxes describe these two different methods. You should only choose one of these options.

"Remove members from group before sync" means that as the first step of the sync, Emma will empty the target group by simply "dumping out" the group's contents. This means that the contacts who are in the group will remain in your audience even after the group has been emptied. If these contacts are members of other groups, they will retain their place in those groups. If they are not in any other groups, they will be in limbo.

"Delete all members before sync" means that as the first step of the sync, Emma will move the entire contents of the target group to the archive. This means that the contacts who are in the group will not remain in your audience after the group has been emptied. Instead they will be in your archive until the import step of the sync pulls them back into your audience.

⚠

Warning

If you choose the "Delete" option, it is important to be aware that archived contacts will not retain their group assignments. This means that even if a contact is restored from the archive by the import step of the sync, they will not be in any other groups, aside from the sync group. If you rely heavily on groups for your audience organization, we encourage you to use the "Remove" option, instead of the "Delete" option. If you do choose to use the "Delete" option, we recommend that you use segments as your primary form of audience organization.

Delete File After Process

This setting determines how Files.com will treat your uploaded file. If you choose this setting, as soon as Emma attempts a sync, Files.com will delete your file. However, Files.com does not distinguish between a successful sync or a failed sync and will delete your file either way. If you attempt to retry a sync after an error, if Files.com is set to delete your file after the process, you will receive another error because your Files.com directory will be empty.

Having a record of past files is helpful for troubleshooting, so if you are frequently encountering errors with your sync, we do recommend that you uncheck this box, at least until we've been able to help you resolve the errors.

Trigger Field Change Workflows

When this box is checked, contacts in the sync who meet the audience and trigger criteria will be eligible to trigger field change workflows. Please note: Field change workflows only work with existing contacts.

✎	Note
	SFTP syncs cannot be used to trigger contact import workflows.

Managing an SFTP Sync

Once your SFTP sync is set up, you will see the sync name and status at the top of your Connect page. To manage your sync, you can use the following options:

• View executions: Allows you to see a list of the past sync runs and their status.
• Edit: Returns you to the SFTP wizard to make changes to the options and settings of your sync.
• Deactivate: Deletes the SFTP sync. You will need to start over if you would like to start another SFTP sync.

To run a sync on demand, click on View executions, scroll to the bottom, and click on the Sync now button. This will start a new sync immediately.