Here you can find all the information you need to set up and work with the Emarsys for Magento 2 integration. Some steps are only relevant to users of Smart Insight or Predict and are clearly marked.
This guide assumes that you already have a working Magento 2 instance. If you need help installing this, please check the Magento documentation.
For release notes and updates, please refer to the Emarsys Github repository.
- Summary of the integration
- Installing the integration
- Configuring the Emarsys connections
- Contact data
- Product data
- Sales data
- Verifying the installation
- Configuring your transactional messages
- Maintaining the integration
Summary of the integration
The Emarsys for Magento 2 integration enables data synchronization (contacts and e- commerce data) between Magento and your Emarsys account, and harnesses the functionality available in the Emarsys Marketing Platform for your Magento e-commerce data.
The main features are:
- Contact synchronization from Magento to Emarsys.
- Opt-in synchronization from Emarsys to Magento.
- One-click implementation of the Web Extend data collection scripts.
- One-click implementation of the Web Recommender framework (for Predict customers).
- Set up Magento events as triggers for personalized communication from the Emarsys platform.
- Automatic export of purchases to Smart Insight.
1. Magento 2 requirements
From Magento you will need:
- A Magento store of version 2.1.x or higher.
- PHP versions 5.6.0 and 7.0.17.
- php5-curl must be installed on your Magento server.
- PHP SOAP extension must be enabled.
- The Sabre/DAV module must be installed in Magento.
- TCP port 21, 32000-35000 must be open (these are required for file transfer over FTPES).
- Set your Magento crons to run every 1 minute.
- Set your server’s PHP memory limit to a minimum of 512 MB. This is because some extension jobs are large and require increased PHP memory.
- Make sure that when an item is added to a cart in your Magento shop, this triggers a page refresh. This is required for the Web Extend data collection scripts to work properly.
2. Emarsys requirements
From Emarsys you will need:
- A fully set up and working Emarsys Marketing Platform account.
If you have more than one Magento site, you can map them to the same Emarsys account or request a separate account for each one. Multiple Magento stores within the same site can only be mapped to the same Emarsys account.
- Your Emarsys merchant ID (this can be found on the Admin menu > Data Sources page in your Emarsys account).
- Your Emarsys WebDAV folder and credentials (for the initial contact data upload and bulk exports).
- Your Emarsys API credentials (for ongoing contact data synchronization).
- Your Emarsys FTP folder and credentials (Smart Insight customers only).
All of the above should already have been set up as part of your standard Emarsys onboarding. If you are missing any of them, please contact Emarsys Support.
- The installation package (available for download here or as a compressed file from Emarsys Support).
- Whitelist the IP address 184.108.40.206 and the range 220.127.116.11/24 (these are required for opt-in synchronization back from Emarsys to Magento).
In addition to these, you will need to create the following in your Emarsys account:
- An external event and campaign for each one of your mapped Magento events (see below).
- All the custom data fields that you need to map to Magento Customer fields.
- Custom fields of the type Short Text field (max. 60 characters) with the following names:
- Magento Customer ID
- Magento Customer Unique ID
- Magento Subscriber ID
You can create these custom fields in Emarsys, or wait until the installation is complete and then create them from the Installation Checklist page in Magento. Note that the names are case-sensitive. For example, Magento customer id will not be accepted by the integration.
3. Multi-store support
If you are connecting multiple Magento stores in different locales, with different languages and currencies, to the same Emarsys account, we need to be able to compare customer behavior and e-commerce data between these stores.
In order to do this, your product catalog must include values in all of the languages that you support, and all your e-commerce (product and sales) and web behavior data must be sent to Emarsys in the same currency and language. In addition please note the following:
- Product catalog - For all your Magento stores or websites that are configured with the same API credentials, a single product data feed will be created with localized values for all the columns that require them. No action is required from you other than ensuring that the same API credentials are used. See Preparing your product catalog: Localization for more information.
- E-commerce and behavior data - To ensure that product and sales data is collected and analyzed consistently, you must set Use base currency to Yes when enabling Web Extend data collection. This will pass all prices in the currency of your default Magento store.
- Web Extend data: language - The
Categorycommand must be sent in the language of your default Magento store.
Installing the integration
You can obtain the Emarsys for Magento installation package from the Emarsys Github repository.
Once you have the package, you should install it in your Magento shop as follows.
1. Install the Emarsys module
- In Github, navigate to emarsys/app/code/Emarsys and then copy the Emarsys folder into your app/code directory in Magento.
You may have to create the appropriate subfolder on your Magento 2 server, and at the end the path will look something like this: /var/www/html/magento2/app/code/Emarsys/Emarsys.
At this stage you should also make sure that all the folders inside the Magento project root are set to be able to write, and they must be owned by both the Magento user and the apache2 usergroup, for example: magento:www-data.
If they are not owned by the apache2 usergroup, you will encounter errors.
- Open a command line, open the Magento 2 installation directory (e.g. /var/www/html/magento2 in the above example) and run the following command to install the WebDAV dependency: composer require sabre/dav ~3.2.0.
- In the same folder, then run the command: composer Update.
- In the Magento marketplace, enter your Magento authentication keys (both public and private). Instructions for this can be found here.
- Now install the Emarsys module with the command: php bin/magento setup:upgrade.
- Then deploy the rest of the required files (js and other static files) to the pub folder with the command: php bin/magento setup:static-content:deploy.
- Update the permissions for the var and pub folders with the command: sudo chmod 777 -R var pub.
- Finally clear the cache with the command: php bin/magento cache:flush.
After installation, you should re-check your folder permissions, as often some new folders or new files are written as the Magento primary user-group rather than the apache2 www-data group, resulting in errors.
If so, you can manually fix this by assigning these to the correct group again. Make sure to pay close attention to the error logs if this happens.
2. Check the installation
Once you have run the commands as described above you can check the status of your Magento system before you proceed. You can do this via the new Emarsys menu available in your Magento backend.
Open the Emarsys menu and go to Operations > Installation Checklist. Here you can see the status of your installation.
- System Requirements - Checks that the Magento prerequisites have been met.
- Extension Settings - At first these will show the default values set by the installation package. You will configure those to your own specifications later in the installation workflow.
- Mandatory Emarsys Customer Fields - Shows Yes if the fields have been found and mapped by the extension during the installation. If not, you will be able to create them in Emarsys directly from the checklist.
3. Enable Web Extend data collection
- For Predict users, these scripts are the basis for the product recommendations.
- For Smart Insight users, they provide the revenue and attribution data.
- For all Emarsys users, they provide the values for the standard set of behavior fields.
The Web Extend scripts are initiated on page load. It is therefore essential that your Magento shop triggers a page refresh whenever a product is added to a cart.
To enable these scripts, open the Emarsys menu and go to Settings > Web Extend and make the following settings.
- Merchant ID - Your Emarsys merchant ID (this can be found on the Admin menu > Data Sources page in your Emarsys account).
- Test Mode - If set to Yes, enables the
- Identify Registered Logged In Customer By - The external key that will identify the contact in Emarsys. In most cases, we recommend using the Email Address. See Selecting the key identifier below.
- Item Unique Identification - The key that will match the items with your product data feed.
- Use Base Currency - Only relevant if you have multiple Magento stores which map to a single Emarsys account.
- If Yes, all prices will be converted to your default store currency before being sent to Emarsys.
- If No, all prices will be sent in the local store currency.
- Track Prices With Taxes - If you have stores in different regions with different levels of sales taxes, you can choose to omit these taxes and send only the net prices to Emarsys.
- If Yes, all prices will be sent including tax.
- If No, all prices will be sent excluding tax.
- Use Ajax Update - If you were unable to exclude the template path from caching as describe in the Magento 2 requirements above, this will help you prevent Web Extend data from being cached.
- If Yes, browser-side refresh of product recommendations is enabled and no Web Extend data will be cached.
- If No, you run the risk of data caching, which could cause data inconsistencies in Emarsys.
When you have made your settings and clicked Save Config, the Web Extend scripts will added to your site's themes and templates and data collection will begin immediately.
4. Enable product recommendations
If you are a Predict customer, you can also define which widgets will be used to display the product recommendations on your various web pages.
To do this, open the Emarsys menu and go to Settings > Predict.
For every page type, select the widget you want installed there.
For more information, see The Predict Web Recommender.
Configuring the Emarsys connections
Emarsys for Magento 2 uses different transfer methods depending on the type of data being transferred.
- The Emarsys API is used for fetching your data from Emarsys (fields, external events, etc.), synchronizing contacts between Magento and Emarsys (in both directions) and pushing Magento events to Emarsys.
- The Product Catalog API is used for synchronizing the product catalog. The configuration settings for this are described in Product Catalog API Settings.
- The Smart Insight API is used for synchronizing sales (order) data. The configuration settings for this are described in Smart Insight API Settings.
- A WebDAV server is required for bulk contact data uploads (including the initial data load).
- An FTP server is required for bulk e-commerce data uploads.
The integration will always use an API over a file server where possible. In other words, if you have configured an API and a file server, the API will be used.
To configure the Emarsys connections, open the Emarsys menu and go to Settings > Connection.
1. API Settings
In the Emarsys API Settings section, make the following settings.
- Enabled – Set this to Yes to enable the plugin.
- API Endpoint – This can be one of the following values:
- Default - This is the recommended option and uses the standard Emarsys API URL for your environment (e.g. https://suitexx.emarsys.net/api/v2).
- Custom URL - This allows you to modify the default URL if required.
- CDN - For customers located outside Europe (e.g. in APAC), you can use a CDN to improve performance. If you think this will be a better option for you, please consult Emarsys Support as we will have to configure some settings on our side.
- Custom API URL – If you have selected this option above, enter your modified default URL here. Make sure you do not include a trailing / at the end of the URL or you will receive an error when mapping fields.
- API Username and API Password – Enter your Emarsys API credentials (not your Emarsys account credentials). These should have been provided during onboarding by Emarsys Support.
Your Emarsys Account Owner can also create new API users and passwords on the Admin menu > Security Settings page, see: API users.
- Click Save Config to save your settings.
- Click Test connection to check that you have entered these credentials correctly.
If a connection has been successfully established between Magento and your Emarsys Marketing Platform account, you will see a yellow confirmation message at the top of the page:
If no connection can be established, you will see an error message instead:
2. WebDAV Settings
In the WebDAV Settings section, make the following settings.
- WebDAV URL, WebDAV User and WebDAV Password - Enter your WebDAV credentials as provided by Emarsys Support. Your Emarsys Account Owner can also create new API users and passwords on the Admin menu > Security Settings page, see: WebDAV users.
- Click Save Config to save your settings.
- Click Test connection to check that you have entered these correctly.
If a connection has been successfully established, you will see the confirmation message at the top of the page.
3. FTP Settings
An FTP connection is required for Smart Insight and Predict users. In the FTP Settings section, make the following settings.
- Hostname, Port, Username and Password - Enter your credentials as provided by Emarsys Support. If you are a Predict customer who does not use Smart Insight, you can enter your own server details here instead.
- Bulk Export Directory - If you have created a sub-directory on the server to separate the bulk (manual) exports from the regular scheduled exports, enter that folder name here (preceded by /).
- Use FTP over SSL(FTPS) - Set this to Yes (recommended).
- Use passive mode - Set this to Yes or No as per your IT requirements.
- Click Save Config to save your settings.
- Click Test connection to check that you have entered these correctly. Magento will display a message to confirm whether it is working or not.
1. Before you start...
Before you start, please read the following section to get an overview of how Magento and Emarsys handle contacts and their data.
About Magento 2 contacts
Magento 2 has two main type of contacts:
- customers (contacts who are able to purchase)
- subscribers (contacts who are subscribed to the web shop newsletter)
These are identified by unique Magento identifiers (the Magento Customer ID and Magento Subscriber ID mentioned in the pre-requisites).
A contact can be both of these types, in which case both values are synchronized in Emarsys under the same contact record, avoiding duplicate email addresses.
Selecting the key identifier
The Emarsys for Magento 2 plugin provides you with two options for the external identifier when synchronizing your contacts.
- Customer ID (recommended) – Selecting Customer ID means that either of the two fields mentioned above are the key identifiers for contacts being synchronized between Magento and Emarsys, rather than the email address, since the latter could manually be changed at any time by the contact in their customer profile.
- Email – If you prefer to use Email, you will need to make sure that you do not have duplicate contacts with the same email address within your Magento contact database, otherwise one of them will not be exported.
The contact synchronization settings can be found under System > Configuration > Emarsys Connect > Contacts Synchronization.
If you are not sure about the right external key to use, please contact Emarsys Support who can provide you with advice based on your current data strategy.
You will need to ensure that your Magento contacts (customers and subscribers) are correctly synchronized with your Emarsys contact database, and that you have the right fields mapped for your segmentation requirements.
2. Contact data field mapping
Magento 2.0 no longer requires both customers and subscribers to have their data fields mapped separately. Instead, you first map all the contact data fields and then you map the values for the single- and multi-choice fields. The mapping that you define here will be used for both the initial data load and all subsequent synchronization, for both types of contact.
Before you start, check that you have created all the fields you need in Emarsys. If not, create them now and click Update Schema to make them available in Magento. Remember to pay attention to the field type when creating new fields.
In both mappings, you can save time by using the Recommended Mapping button. This will try to identify and associate matches based on field name similarity. If you use this, you should still verify every single mapping to make sure that they are correctly associated.
If you have more than one Magento store, you will have to repeat these steps for each store separately.
To map your contact data fields, open the Emarsys menu and go to > Mappings > Customer.
- If you have more than one store, select the right store from the Store View drop-down:
- In the Select Mapping drop-down, Select Customer. You will now see all the Magento customer attributes and can map them to Emarsys attributes (contact data fields).
- If you have not already done so, click Update Schema to make sure that all your Emarsys fields are available in the Emarsys Customer Attributes column.
- For each Magento Customer Attribute, select the appropriate Emarsys field from the drop-down. You can search for a particular attribute using the Search field.
Make sure that you map Emarsys fields of the same type. If the field type is not appropriate for the data, you will run into problems when creating segments in Emarsys based on these fields.
- When you are done, save your changes to display the new mapping.
- Now select Customer-Field from the Select Mapping drop-down.
- All the single-and multi-choice fields that have been mapped are shown and you must now map the values for each one.
3. Prepare the Emarsys auto-import
Once you have mapped all your fields, you will need to set up two auto-imports in your Emarsys account, one for Magento customers and one for subscribers.
In your Emarsys account, open the Contacts menu > Auto-imports and make the following settings:
Source File Settings (the first page of the wizard)
- Where to look for the import file - Select Emarsys WebDAV and enter the path.
- Import file settings / File name - The Magento initial load files will be named customers_<timestamp>.csv and subscribers_<timestamp>.csv, so you should enter customers_*.csv and subscribers_*.csv for your two auto-import profiles.
Sample File (second page)
- You will need to upload a sample file containing the header and at least one line of the file you will use for your initial load, with all your mapped fields. You may have this from your staging system, otherwise you can make an initial export to the WebDAV and use that file.
Match Fields (third page)
- Check that the fields are correctly mapped and select your unique identifier.
When you have finished, make sure that the status is set to Enabled on the Auto-imports on the overview page.
The same auto-import will also be used for the contact synchronization failsafe mechanism (see below). After the initial load has been performed, you may want to return to your Emarsys auto-import and change the name to differentiate later imports from the initial one.
4. The initial contact data load
Once you have prepared your customer data as described above, you can perform the initial data load to import all your Magento customers and subscribers to Emarsys.
If your contact database contains fewer than 10,000 records, the initial data load will take place using the Emarsys API. Otherwise it will use the WebDAV for file transfer.
Open the Emarsys menu and go to Settings > Contact Synchronization.
- In the Initial DB Load section and select the opt-in status for the contacts you will import, choosing from:
- Set opt-in status for all users to true - Enables Emarsys to send to all imported contacts straight away. We recommend NOT to use this option as you risk sending campaigns to contacts who did not explicitly opt in to them.
- Set opt-in status for all users to empty - You cannot send to any contacts from Emarsys until their opt-in has been confirmed by another method (i.e. double opt-in).
- Set opt-in status true for all users depending on attribute - You can overwrite the Magento opt-in value to
TRUEfor your Magento customers according to the value provided by Magento in the Subscribed Status attribute.
Multiple selection is currently not available for this drop-down, so you must repeat the export for each of the different Subscribed Status values.
- Click Export to synchronize all your Magento customers to Emarsys.
Once the initial data load is complete and the integration is synchronizing the data across both systems regularly, opt-in status is handled on a per-contact basis as they sign up for, opt-in or opt out of content. This is the only data that is synchronized both ways, with the latest timestamp taking precedence.
Do not save any Contact Synchronization Settings before you make the initial upload, as this will immediately begin to synchronize data according to your schedule, and you may end up overwriting data when the initial load is performed.
5. Contact synchronization settings
Once the initial data load has been performed, you will need to define the settings for the ongoing synchronization of new data.
If you make any changes to the field mapping, the new fields will be synchronized for new contacts only. To update the new fields for existing contacts, you will have to run another bulk export (see Maintaining the integration below).
There are two methods for keeping contact data synchronized, Realtime-failsafe and Background.
- Realtime-failsafe (recommended) - This maintains contact synchronization in real time using the Emarsys API, sending every update to Emarsys as it occurs in Magento. This option is suitable for use cases where Emarsys needs the data immediately (e.g. for automated engagement programs). In case of unsuccessful updates (e.g. due to network downtime or excessive volume), they are placed in a failsafe queue and are processed once a day according to your Background Runtime and Background Frequency settings.
To enable this option, set Realtime-failsafe to Yes.
- Background only - This collects and queues all contact updates and synchronizes them together according to your Background Runtime and Background Frequency settings, using your Emarsys WebDAV folder. This option is suitable when there is no urgency for the data to be transferred to Emarsys, and there is no limit to the volume of data being synchronized.
To enable this option, set Realtime-failsafe to No.
- Background Runtime - Here you enter the time of day (in HH:MM:SS) when your failsafe export will run (if you are using the Realtime-failsafe option), or when your regular Background export.
- Background Frequency - The options are Daily and Hourly. If you select hourly, the sync will run at the minutes and seconds past each hour as defined above.
- Unique Field - This is the unique identifier that will ensure the data is synchronized to the right contact in Emarsys. You can choose from the email address, the Magento ID or a combination of email address, website ID and store ID.
Email#WebsiteID#StoreId is our recommended option, but bear in mind that if you have multiple stores, this will create separate Emarsys contacts per store, even if it is the same person making the purchase.
Once you have set the Unique Field and synchronized your first contact, this setting cannot be changed.
- Notification secret key - Here you can enter any password or secret you like. It is purely an internal security code to protect your data files from external interference.
When the extension needs fresh data, it calls the Emarsys API to kick off an export. Instead of pinging Emarsys every few seconds to check when the export is ready, the extension provides a URL which Emarsys can call when the export is completed, so that Magento can pull the data.
Calling this URL from the import process essentially forces Magento to check an Emarsys export, therefore the URL must be as unique as possible to avoid DOS attacks that will reflect on the Magento instance and Emarsys. The Notification secret key is used to ensure that the URL is unique.
You should use only alphanumeric Latin characters for this key (a-z, A-Z, 0-9). See https://perishablepress.com/stop-using-unsafe-characters-in-urls/ for more information.
6. Opt-in settings
You must now define how your web shop handles opt-ins and opt-outs. The actual events that trigger the opt-in confirmation messages are mapped when you configure your transactional messages, described below. To configure your opt-in strategy, go to Emarsys > Settings > Opt-in.
- Enable Opt-in - If this is set to Yes, you override the default Magento opt-in settings with the settings you configure in this integration, and can trigger confirmation messages from Emarsys.
- Opt-in strategy - There are two options available:
- Double-Opt-In - This is our recommended method as it ensures that the person who subscribes is the same as the person who owns the email address used. You will be asked to map two Emarsys events for your transactional emails - one to trigger the confirmation email and one to update the opt-in status after the customer has clicked the confirmation link.
- Single-Opt-In - You only need to map the one event to update the opt-in status immediately.
- Newsletter Subscription on Checkout - This enables you to add a newsletter opt-in checkbox to your checkout page. Paste the code snippet on your checkout page as described and the opt-in information will be passed to Emarsys.
It is strongly recommended to manage the opt-in status as far as possible in Emarsys. If you change the status in Magento, it could take up to 24 hours to reach Emarsys in the case of a Background or failsafe sync, during which time the contact could possibly receive further emails.
7. What data is synchronized?
- From Magento to Emarsys - The Magento contact database is considered the master database for contact details, and all values synchronized for the mapped fields will overwrite the existing values in the Emarsys application.
New contacts will be exported to Emarsys with the same fields as per the initial export.
- From Emarsys to Magento - Once a day, at the specified Background runtime, Emarsys also checks if the Opt-in field of any Magento contacts has been modified. If so, this change is synchronized back to Magento.
Whenever the opt-in field is synchronized, the integration checks the last modified timestamp in both systems and the latest timestamp always takes priority. This is to prevent an unsubscribe action in Magento being overwritten by the former value in Emarsys.
If you are using Smart Insight and/or Predict, you will need to ensure that your Magento product catalog is correctly loaded to Emarsys and kept synchronized.
Unlike contact and sales data, the entire product catalog is always overwritten rather than simply applying the delta. Therefore, the initial load and ongoing synchronization are actually the same process.
The recommended method for this is to use the Product Catalog API. If you do not use this method, you must configure the FTP server as described above, and you will have to configure some settings on the Product Catalog page of your Emarsys account. If both methods are configured, the API will be used.
1. Product Catalog API settings
To configure the Product Catalog API, open the Emarsys menu and go to Settings > Product Catalog and scroll down to the bottom of the page.
- Enable API Export - Set this to Yes.
- Merchant ID - Your Emarsys merchant ID (this can be found on the Admin menu > Data Sources page in your Emarsys account).
- Bearer Token - You will receive this from Emarsys Support.
2. Map the product attributes
You should map your Magento product attributes fields to the correct Emarsys product catalog fields, ensuring that your product catalog has the correct columns and field types to conform to our product catalog standards. For more information, please see: Preparing Your Product Catalog.
To map your product attributes, go to Emarsys > Mappings > Product. If you have more than one store, remember to select the right store from the Store View drop-down.
Here you map the columns of the product data feed. For each Magento attribute, select the appropriate Emarsys field.
- Add Emarsys Attribute - If you are missing an Emarsys field, you can create the column header here. The field name will automatically have the prefix c_ added.
This will not create the field in Emarsys; you must go to your Emarsys account and do this manually. For this reason it is recommended to create the field first in Emarsys and then click Update Schema to import it to Magento.
- Update Schema - Imports all the available Emarsys fields to Magento.
- Recommended Mapping - Auto-maps fields based on their names. This can be a helpful time-saver if you have a lot of fields.
When you are finished, click Save to save your settings.
3. Configure the product data feed
Once you have mapped your product data fields, set up the schedule for the synchronization of your product catalog. To do this, go to Emarsys > Settings > Product Catalog.
If you need to upload your catalog immediately, you can do this by making a bulk export.
- Enable nightly product feed export - Set this to Yes.
- Include Bundle Products - If set to Yes, this will include bundle products in the feed.
- Exclude Categories - If you want to exclude any product categories in the catalog, select them from the tree view.
- Execute and Export at - Sets the time of day for the product feed ( in HH:MM:SS).
- Frequency - Set this to Hourly or Daily, depending on your requirements.
- Hourly - Recommended if your product catalog changes multiple times per day. This is also required for features such as Predict Abandoned Cart.
- Daily - If your product catalog is very large, or changes less frequently, select this option to reduce the load on your system.
When you click Save Config the product catalog will be exported from Magento to Emarsys according to your defined schedule. With every export the entire catalog will be overwritten with the new one.
If you are using Smart Insight, you will need to ensure that your Magento sales (order) data is correctly loaded to the Emarsys Smart Insight database and that you have the right attributes mapped for your Smart Insight segmentation requirements.
The recommended method for this is to use the Smart Insight API. If you do not use this method, you must configure the FTP server as described above. If both methods are configured, the API will be used.
1. Smart Insight API settings
If you are using the Smart Insight API, go to Emarsys >Settings > Smart Insight and scroll down to Smart Insight API Settings.
- Enable API Export - Set this to Yes.
- Merchant ID - Your Emarsys merchant ID (this can be found on the Admin menu > Data Sources page in your Emarsys account).
- Bearer Token - You can find this in your Emarsys account on the Admin menu > Data Sources > Sales Data page, when you click Show API upload details.
- Maximum Records - This defines how many records are transferred with every API call. You can choose from a range between 100 and 10,000 records, depending on your requirements.
2. Map the order attributes
First, go to Emarsys > Mappings > Order. Here you give the Magento order columns the names that will appear in the Smart Insight screens as Purchase attributes.
There is a fixed default set of columns already mapped - these are named in the Emarsys Order Attribute column and cannot be changed.
You can add any other columns to the export by entering an attribute name. If you leave this field empty, that column will not be included in the export file.
3. The initial sales data load
When you have named all the columns in the export file, you should make a bulk export of your historical sales data. To do this, open the Emarsys menu and go to Operations > Bulk Export.
- Export Entity Type - Select Order.
- From and To fields - Select the time range for the Magento order data. There is no limit to the data you can export, but we recommend to include at least the last two years if you can.
- Export To - Select CSV.
Click Export. The Magento order data will now be loaded to the Smart Insight database and will be available for Smart Insight segmentation in Emarsys.
Do not save any Smart Insight Settings before you make the initial upload, as this will immediately begin to synchronize data according to your schedule, and you may end up with some sales data being loaded twice when the initial load is performed. Smart Insight does not de-duplicate sales data and repeated orders will adversely affect your eRFM scoring and your e-commerce data model in general.
4. Sales data synchronization settings
After your initial sales data load, you must configure the ongoing load of new sales data. To do this, go to Emarsys > Settings > Smart Insight.
- Smart Insight Enabled - Set this to Yes.
- Export using email as identifier - If set to Yes, the email address of the Magento contact will be added to the export file and used to map the sales data to an Emarsys contact, instead of the Magento Customer ID. This is important if you are including Magento Subscribers in your marketing campaigns, as you do not have a Magento Customer ID for them.
- Export guest checkout orders - Defines whether or not guest (i.e. anonymous) orders will be exported. These cannot be used for Smart Insight segmentation but they will help to improve the product affinity model.
- Frequency - Hourly or Daily. We recommend to set this to hourly as this will keep the export files smaller.
- Order Export for Statuses - The Emarsys web collection scripts will pass most of your sales data events to Emarsys, but there are some events that these scripts do not track, for example shipping information, expected delivery dates or payment methods with third-party providers such as PayPal. In order to use this information in Emarsys, select the statuses for which orders should be exported. You can make multiple selection by holding down the CTRL key.
When you click Save Config, Magento will export all the orders which have transitioned to one of the selected statuses since the last export, at the appointed time.
This feature simply exports the data to Emarsys. You will have to make sure that the right fields exist in the Emarsys database for you to be able to act on this data.
Verifying the installation
To test that the contact data synchronization is working, proceed as follows:
- Create a new dummy account in your Magento store.
- Log in to the shop with the dummy account.
- Make a test order.
- Update the user profile.
- Monitor the Emarsys database to track the data changes.
To test that the e-commerce data synchronization is working, proceed as follows:
- Add a new product to your Magento store.
- Wait for the product data to be synchronized (as per your configuration).
- Query the data in Emarsys to see that the new product has been imported correctly.
Configuring your transactional messages
Magento 2 has a number of customer-facing events, some of which can be used as triggers for transactional campaigns in Emarsys. You will need to map these events to the external events in Emarsys which will trigger the campaign. You can also map Magento variables to placeholders in Emarsys and personalizes your message content.
1. Prepare your Emarsys campaigns
For every Magento event you want to map, you will need to create the following in your Emarsys account:
- One external event per Magento event.
- One campaign per external event. These should be created directly in the campaign creation interface for that channel (Triggered Email, SMS, Mobile Engage, etc.). If you intend to follow up the initial message with further actions, you can include this in an Automation Center program, but this is typically not the case for transactional messages.
- A list of personalization placeholders that you can map to the Magento variables for each event (see below).
2. Map the events between Magento 2 and Emarsys
When you have prepared your campaigns in Emarsys, go to Emarsys > Mappings > Events.
- For every available Magento event, select the appropriate external event in Emarsys.
- Update Schema - Imports all the available Emarsys events to Magento.
- Recommended Mapping - Auto-maps events based on their names. This can be a helpful time-saver if you have a lot of events.
Single and double opt-in events
There are two events in Magento that manage your newsletter opt-in strategy. Depending on what you configured for your Opt-in Settings, you will need to map the following events accordingly.
- Single opt-in - Only the Newsletter Subscription Success event needs to be mapped to a message confirming the successful registration. Newsletter Subscription Confirmation will not be triggered.
- Double Opt-in - You should map Newsletter Subscription Confirmation to the Emarsys event that triggers the message containing the confirmation link. You should then map Newsletter Subscription Success to the event that triggers the message confirming the successful registration.
Available Magento events
The following Magento events are currently available for mapping:
- Contact Form
- Credit Memo Update
- Credit Memo Update for Guest
- Forgot Admin Password
- Forgot Password
- Gift Registry Sharing
- Gift Registry Update
- Invoice Update
- Invoice Update for Guest
- New Credit Memo
- New Credit Memo for Guest
- New Invoice
- New Invoice for Guest
- New Order
- New Order for Guest
- New RMA
- New RMA for Guest
- New Shipment
- New Shipment for Guest
- New Account
- New Account Confirmation Key
- New Account Confirmed
- Newsletter Subscription Confirmation
- Newsletter Subscription Success
- Newsletter Unsubscribe Success
- Order Update
- Order Update For Guest
- RMA Admin Comments
- RMA Admin Comments for Guest
- RMA Authorization
- RMA Authorization for Guest
- RMA Customer Comments
- Remind Password
- Rewards Points Balance Update
- Rewards Points Expiry Warning
- Send Product to a Friend
- Share Wish List
- Shipment Update
- Shipment Update for Guest
- Store Credit Update
3. Personalizing your message content
Since your Magento contacts are synchronized with Emarsys, you can of course include in your message content all the regular personalization options available in Emarsys, including conditional content and block targeting. However, there may be important information about the event that is only available in Magento (for example, the URL of the confirmation link in a confirmation email).
To add this Magento content to your Emarsys email, you must add special Magento placeholders to the email content.
In your Emarsys account, add the placeholders to the email content, with a double-% either side (for example, the variable
first_name should be written in the email content as
These placeholders can be any text string and are only used to make sure the right values in the JSON object are added to the right place in the email. They do not reference the Emarsys database and do not have to be the string IDs of Emarsys fields. We recommend that you name them as closely as possible to the Magento variables you will match them to.
You will need to map these for each event so you should carefully track which placeholder you have included in which transactional message.
4. Map the placeholders
When you have mapped your events, you can map Magento variables with the placeholders you added to your Emarsys campaign content. For each event, click Placeholders.
For each Magento variable, add the Emarsys placeholder that you will include in the message content. This can be any text string without spaces and will be included in the message between double % symbols. See
5. Check the JSON
It is a good idea to check the JSON payload that will be transmitted to Emarsys, to make sure all the placeholders have been correctly mapped. To do this, click JSON Request next to each event to display the object; now you can check the placeholders and see exactly what data is being passed to Emarsys without having to refer to the logs.
This will show only the Magento JSON request that is sent to Emarsys, and will not include any content or personalization that you have included in the Emarsys message content.
6. Enable transactional messages
When you have finished your mapping, go to the Emarsys menu, Settings, Transaction Email and enable this functionality.
- Enable Emarsys Transaction Emails - Set this to Yes.
From this point on, all the mapped events in Magento will trigger the corresponding external event in Emarsys. You can then link these events to whichever action in Emarsys that you want (e.g. launch email, SMS or Mobile Engage campaigns).
Maintaining the integration
Data monitoring in Emarsys
Once you have made your initial data loads and set up the schedule for regular synchronization of new data, you can take advantage of the data monitoring tools that Emarsys provides to make sure that the data flow is working properly.
These tools validate every data import into Emarsys. If an issue is identified, this is highlighted and a suggested solution offered.
The tools are located in your Emarsys application on the Admin menu, Data Sources page.
New versions of the plugin
If there is a new version of this integration, you will be informed via the Magento notifications. A link will be provided to the Emarsys GitHub repository where you can download the latest version. You then need to follow the steps described above in Installing the Emarsys for module. All your settings and configurations will not be affected.
Keeping your Magento schema updated
If you create new assets (fields, external events, etc.) in Emarsys, you can update your Magento interface at any time by clicking Update Schema.
You can also set up a regular check to run in the background to see if any new assets have been created. To do this, open the Emarsys menu and go to Settings > Transactional Email and set the time and schedule for the check.
If the check finds a new asset, you will receive a notification prompting you to update your schema again.
Making a bulk export
Under Emarsys > Operations > Bulk Export you can make a one-off manual sync of your Magento data to Emarsys at any time.
You have four options for exporting data.
- Customers and Subscribers - Select these if you want to update your Magento contacts in Emarsys, for example after you have added a new Magento field or changed the field mapping.
- For Customers, you will need to enter a time range. All customers registered during this time range will be synchronized.
- For Subscribers, you do not define any time range. All subscribers in your Magento account will be synchronized.
If you do map new fields for customers or subscribers in Magento, make sure to update the corresponding Emarsys auto-import profiles.
- Order - This is mainly used for the initial sales data load. You can later sync all order data within a specific timeframe, for example if your web shop has been offline for some time, but you should be very careful when doing this as Smart Insight will not de-duplicate the data and you could end up with duplicate orders, which will affect your eRFM scoring and your e-commerce data model in general.
- Product - Since the entire product catalog is uploaded every time, this is only useful if you want to make an immediate sync of your product catalog and not wait for the scheduled sync. As per the product data feed settings, you can choose to exclude certain product categories from the sync.
Under Emarsys > Operations > Logs you can find a list of all the integration events between Magento and Emarsys. This will help you debug the integration during installation, and monitor it afterwards.
For more details on an individual event, click View.
Under Emarsys > Settings > Logs you can define how long to store the logs for, clean up your log files, set up a schedule for log reports and download the current log files.
- Save Log Days - This is how long we store the logs for the integration.
- Enable Log Cleaning - Enables the automatic deletion of outdated logs.
- Send Log Report - Once a day this downloads the logs for the previous 24 hours and emails them to Emarsys Support.
- Download Logs - Downloads the entire log file locally as a .csv file.
- Clear Logs - Deletes all the saved logs.
- Clear Cron Details -
Under Emarsys > Help > Support you can open a support ticket directly from your Magento interface.
When clicking the Field mapping drop-down on the Contacts synchronization page, if you see the message No fields available in Emarsys Suite for this website (please check API configuration) this means you have a trailing slash (/) at the end of your custom API URL. You should remove the trailing slash.
Invalid cache types after updating the configuration
After you make any changes to the plugin configuration, you may see this message:
One or more of the Cache Types are invalidated: Configuration, Page Cache. Please go to Cache Management and refresh cache types.
This is normal Magento behavior; just click the link provided and flush Magento cache.