Here you can find all the information you need to set up and work with the Emarsys for Magento integration. Some steps are only relevant to users of Smart Insight or Predict and are clearly marked.
This guide is compatible with the following Magento versions:
- Community versions 1.7, 1.8, 1.9.
- Magento Enterprise versions 1.12, 1.13, 1.14.
This guide assumes that you already have a working Magento 1 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 Emarsys for Magento 1 package
- 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 1 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.
- Set up Magento events as triggers for personalized communication from the Emarsys platform.
- Automatic export of purchases to Smart Insight.
1. Magento 1 requirements
From Magento you will need:
- For Community Editions older than 1.8, and Enterprise Editions older than 1.13.1, replace the
curl.phpfile located in MAGE_ROOT_DIR/lib/Varien/Http/Adapter/ (the replacement file is provided by Emarsys). The older
curl.phpfile cannot handle the headers passed from the Emarsys API, and will not show the list of fields on the mapping page.
- 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.
- AOE Scheduler (or similar) is not mandatory but highly recommended as this exposes the scheduled tasks visually and will help us to support you. Please note that AOE Scheduler is not available for PHP 5.6 and higher.
- Set your Magento Cron to run every one minute for Magento Enterprise editions, and every five minutes for Magento Community editions. Some scheduled jobs are too large for the Magento scheduler to handle, and will timeout if attempted. You can check the Magento documentation for instructions on how to do this or ask your Magento provider to do it for you.
- TCP port 21, 32000-35000 must be open (these are required for file transfer over FTPES).
- Make sure you have the necessary access level to install extensions from the Magento Marketplace in your Magento shop.
- Admin access to both the staging and production panels is required for Emarsys to support the Extension, as well as SSH access to your web server (direct SSH access is preferred, but not mandatory, as long as there is a resource on your side that can access the server when required).
2. Emarsys requirements
If you have ever used a previous Magento integration from Emarsys, make sure that this has been uninstalled. Otherwise, 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 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).
- Whitelist the IP address 18.104.22.168 and the range 22.214.171.124/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 Subscriber ID
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 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 category names sent in 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 the /app/ folder and then copy the app folder and package.xml file to the Magento project root, e.g.: /var/www/html/magento/.
2. Clear the Magento cache
- Return to the Magento admin module, go to System > Cache Management and click Flush Magento Cache.
- Log out of the Admin module and then log in again.
- You will now see a new entry in the System > Configuration menu: Emarsys Connect.
- The Dashboard of the Magento Admin Panel will now also have a new menu entry: Emarsys Email:
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.
To enable these scripts, open the System menu and go to Configuration > Emarsys Connect > Web Extend and make the following settings.
- Enable Web Extend - 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).
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 we unable to exclude the template path from caching as describe in the Magento 1 requirements above, this will help you prevent Web Extend data from being cached.
- If Yes, no Web Extend data will be cached.
- If No, you run the risk of data caching, which could cause data inconsistencies in Emarsys.
Use jQuery - If your Magento site supports jQuery, this should be your preferred option, otherwise the Ajax Update method will be used.
- If Yes, 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.
Configuring the Emarsys connections
Emarsys for Magento 1 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. It is also used for the initial contact data load.
- An FTP server is required for bulk e-commerce data uploads.
1. API Settings
To configure the Emarsys API connection, open the System menu and go to Configuration > Emarsys Connect > Suite settings.
This shows how many new customers have registered on the site since the last data sync. This counter is reset to zero after every sync (this can sometimes take a few minutes, depending on network connectivity).
- Enabled – Set this to Yes to enable the plugin.
API Endpoint – This can be one of two 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.
- Debug – If set to Yes, this logs additional integration events, which is useful when you want to enable additional debugging logs to check specific activities (e.g. tracking the synchronization activity as we start exporting contacts and sales files after installation).
- Plugin profiler – If set to Yes, this logs the time and resources consumed by the plugin for performing any specific action. See: About logging, below.
- Clean module log files - This deletes the latest log files. If you leave your logging options enabled after the integration has been successfully installed, you should do this regularly (daily).
- Download module log files – Downloads the log files for whichever logging options you have enabled.
- Cron service API ping – This must be Enabled, since it allows the extension to establish that the connection is active and logs the errors when it is not (if Debug is set to Yes). Loss of connection will cause the API calls to queue, limiting the real-time features of the integration. This ping will will enable you to see when and why the connection was lost.
Suite API Username and Suite 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. The Test connection button should turn green to signal that the connection has been established between Magento and your Emarsys Marketing Platform account.
We recommend to keep both the logging options set to Yes until you have fully set up and tested this integration. This will help you (and us) identify the causes of any issues that arise.
The Plugin Profiler monitors the time and memory allocation of an application loading cycle at specific intervals. By enabling the Plugin Profiler setting, we can collect information regarding the overall time and resources consumed by the plugin for performing any specific action.
When this setting is enabled, it logs the related data into a log file called emarsys-profiler.log that can be downloaded via the Download module log files button and link.
The log file contains following data:
- Count - The number of times a particular code was used/executed.
realmem and realmem_start - This column show the amount of memory allocated to PHP. It is a mix of the core PHP
memory_get_usage()function without the
TRUEparameter passed to it, minus timer values.
- emalloc and emalloc_start - This column shows additional PHP values that help to detect memory issues.
In some instances of Magento, enabling the Plugin Profiler can cause issues. If you receive such an error message from Magento, you can switch Plugin profiler to No if Debug is set to Yes. In this way, you will still be able to log some of the integration events, if not all of them.
Once installation is complete, you should turn both options to No.
From then on, should you feel that the integration is not performing as expected:
- Clean the module log files
- Enable both logging options
- Debug the integration
- Clean the log files again
- Disable both logging options
2. FTP Settings
An FTP connection is required for Smart Insight and Predict users. To configure this connection, open the System menu and go to Configuration > Emarsys Connect > Smart Insight > FTP Settings.
- Hostname, 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.
- Directory - If you have created a sub-directory on the server to separate the 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 when you are done.
- Click Test Connection to verify everything is working. 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 1 contacts
Magento 1 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 1 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.
If you do select Customer ID, please note that the option to export guest checkouts will not be available.
2. Contact data field mapping
Magento customers have a very complete customer profile offering a number of fields. Depending on your business model and needs, you will probably only be interested in a subset of these fields.
In contrast, Magento subscribers only have four fields available for synchronization:
- First name
- Last name
- Email address
- Subscription status (opt-in)
To map fields between Emarsys and Magento, go to System > Configuration > Emarsys Connect > Contact Synchronization and open the Field mapping section.
Click Update Schema to ensure that all your Emarsys fields are available in Magento.
Select each Magento field you want to synchronize, and the appropriate target field in the Emarsys application, and then use the right arrow to move the mapped pairs across.
Before you start, check that you have created all the fields you need in Emarsys. If not, create them now and click Update Schema again to make them available in Magento. Remember to pay attention to the field type when creating new fields.
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.
Note: As well as the fields you select for mapping, three Magento fields are always included for synchronization by default:
- Customer ID
- Subscriber ID
Value mapping for single- or multi-choice fields is not supported. You should use only simple text fields (numeric or alphanumeric) to map your data to Emarsys.
3. 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.
Open the System menu and go to > Configuration > Emarsys Connect > Contact Synchronization and open the Synchronization Settings section.
- Enable Customers export and Enable Subscribers export - Set both of these to Yes to enable the two Export buttons (after you have made your export you should set them both back to No).
- Use Secure Notification URL - If your web shop URL starts with https://, this must be set to Yes. This can be set to No for test or staging installations.
- Synchronization mode – Ignore this for now.
- Background Runtime – Ignore this for now.
- Notification secret key – This is the password required for the export notifications.
- Key Id – Select your unique identifier for the contacts.
When you are finished, you can make the initial data load by clicking the two Export buttons. You can have both exports running at the same time, but you should not start them together as they both need a few seconds to initiate the export. The exact time will depend on the size of your database but the system will inform you if you start the second export too quickly.
When you make the initial data load, the following will happen:
- For Magento customers, all the fields defined in the Field Mapping above will be synced, along with the Opt-in and Customer ID fields.
- For Magento subscribers, only the First name, Last name, Email address, Opt-in and Subscriber ID are synced.
The sync will start at the next multiple of five minutes. If the process looks stuck, you may need to flush the Magento 1 cache, see: Troubleshooting.
The initial data load uses the Emarsys API, which processes the contacts in batches of 10,000. Depending on the number of contacts and fields to load, this process may take anywhere from a few minutes to a couple of hours (for a database of over 10 million contacts, for example).
About the Notification URL and secret key
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.
4. 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.
In Synchronization settings section, make the following settings:
- Enable Customers export and Enable Subscribers export – Set these back to No to disable the two Export buttons, preventing an accidental sync of your entire contact database.
- Synchronization mode – Select Realtime-failsafe or Background only as per your requirements (see below).
- Background Runtime – Set the time of day for the daily data synchronization.
Click Save Config to save your settings. The next export take place at the scheduled time.
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.
Realtime-failsafe vs Background only
Contacts synchronization can be scheduled in two ways:
This maintains contact synchronization in real time, sending every update 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 at the specified Background runtime (see below).
Important note: you should discuss your needs with Emarsys Support to ensure that you have the right API configuration to handle your requirements in terms of volume of traffic.
This synchronizes all contact updates that have occurred in the 24 hours up to the specified Background runtime. 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.
Here you enter the time of day when your failsafe export will run (if you are using the Realtime-failsafe option), or when your daily export will run (if you are using the Background only option).
5. 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. For Magento customers, new contacts will be exported will the same fields as per the initial export. For Magento subscribers, only the Email address and Opt-in fields are exported, since the First name and Last name fields cannot be modified in Magento.
- 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.
However, it is strongly recommended not to change the opt-in status in the Emarsys application as it will take up to 24 hours to update to Magento, during which time the contact could possibly receive further (transactional) emails. Best practices would be to update it in Magento, so the Emarsys contact will be updated as specified in the synchronization mode.
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 data is correctly loaded to Emarsys and kept synchronized.
Unlike contact and sales data, the entire product catalog is always exported rather than simply the delta. Therefore, the initial load and ongoing synchronization are actually the same process.
1. 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 the product attributes, go to Emarsys > Product Attribute Mapping.
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 Mapping to save your settings.
2. Configure the product data feed
Now go to System > Configuration > Emarsys Connect > Full Catalog Export. Here you configure your product data feed and select the product types to include in it.
- Enable Full Catalog Export - Set this to Yes. It does not matter if a scheduled export occurs before you have made your initial load as the entire catalog is always overwritten every time.
- Include Disabled Products - Includes products that are no longer available for sale. In most cases this should be set to Yes, to ensure long-term data consistency.
- Include Product types - Here you select which product types to include. Refer to the Magento documentation for more details.
- Start time - Sets the time of day for the product feed (in HH:MM:SS).
- Frequency - Set this to Daily. The options Weekly or Monthly should be used only if you are sure that you do not change your product catalog more frequently than this.
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.
1. The initial sales data load
You should first make a bulk export of your historical sales data. To do this, go to System > Configuration > Emarsys Connect > Smart Insight.
If you have not already configured your FTP server as described in FTP Settings above, you should do so now.
- Smart Insight enabled – Set this to Yes.
- Export using email as identifier – Set this to Yes to ensure you do not create duplicate contacts. If No, the Customer ID will be used, which will disable the Export guest checkout orders option (since we do not have Customer IDs for guest checkouts, only email addresses).
- Export guest checkout orders – Select Yes if you want to push anonymous order data to Smart Insight (this will be used to improve the product affinity and other metrics).
- Execute at - Set this to a fixed time that will not trigger an export before the initial data load is completed. For example, if the current time is 14:00, set it to 12:20. It is important that no scheduled feed takes place while the initial data load is being processed, otherwise you could end up with duplicate sales data in Emarsys.
- Include Bundle products - If set to Yes, this will include bundle products in the feed.
- Use Base Currency in Export - This must have the same value as Use base currency in the Web Extend data collection settings. This will ensure that both the data collected by Web Extend and the data loaded by Smart Insight are consistent in terms of currency and language.
- Calculate bundle price - Set to Yes if you want to include the total bundle price in the data file.
When you have made your settings, click Generate Now to export the last two years of order data and pass that to Emarsys. You should verify that the .csv file created contains all the orders of last the two years with all the required fields (product id, price, quantity, etc.) correctly filled.
2. Exporting orders by status
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.
You can pass this information to Emarsys and use it for Smart Insight segmentation or as part of an automated program by including these statuses in the export.
On the same page, in the Order Statuses section, 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 include orders which have transitioned to one of the selected statuses in the sales data synchronization feed.
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.
3. Sales data synchronization settings
When you have made your initial export, reset the Execute at field to the time of day or frequency that you require, and 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.
- In the .csv file the orders which have a credit memo are also displayed, but with a negative price.
- Once the orders are exported, the queue is emptied so the same orders will not come in the next export.
- Check that the products .csv file is generated with all the products related to the orders you created and that all the required fields (product id, price, quantity, etc.) are correctly filled.
4. Magento bundles
If you set the field Include Bundle products to No, your export file will contain only the product data:
If you set the field to Yes, then the Bundles will be included as an extra line in addition to the product data:
If you set the field Calculate the Bundle price to No, the price for each item in the Bundle is listed independently and the price for the Bundle is set to zero:
If you set this field to Yes, the Bundle price will display the total for all items in the Bundle and the items themselves will have their price set to zero:
Verifying the installation
To verify that your configuration is working, perform the following checks.
Verify customer sync to Emarsys
- Create a customer from the Magento backend or frontend.
- Click Export Customers
- Log in to your Emarsys account.
- Search for the customer using the in contacts by email option and entering their email address.
- In the Search Results page click the edit icon to open the contact properties.
- Verify whether the same customer is displayed or not.
Verify subscriber sync to Emarsys
- Create a subscriber from the Magento backend or frontend.
- Click Export Subscribers
- Follow the remaining steps as described above.
Verify daily order export (also for guest orders)
- Create a guest order from the Magento frontend.
- Create a customer order from the Magento frontend or backend.
- Change the status of both orders to Processing, Closed or Complete.
- In Smart Insight settings, check that Export using email as identifier and Export guest checkout orders are both set to Yes.
- Run the export manually.
Check that the sales_items .csv file contains both of the orders you created above with all the required fields (product id, price, quantity, etc.) correctly filled.
Configuring your transactional messages
In Magento you can define certain transactional messages, for example a Confirmation Link email, Welcome email or Order Confirmation email. These messages can be triggered in Emarsys by mapping the Magento events to Emarsys external events and then link those to an Emarsys 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 1 and Emarsys
When you have prepared your campaigns in Emarsys, open the Emarsys Email menu.
- Click Magento Events to display the list of default Magento events, their configuration path and the associated template.
- To add a Magento template to the list, go to System > Transactional Emails.
- Go to the configuration path and select the required template from the drop-down.
- The selected template will now be listed under Magento Events.
SUPPORTED MAGENTO EVENTS
The following Magento events are supported by the integration:
Credit Memo Update
Credit Memo Update for Guest
Forgot Admin Password
Gift Registry Sharing
Gift Registry Update
Invoice Update for Guest
New Credit Memo
New Credit Memo for Guest
New Invoice for Guest
New Order for Guest
New RMA for Guest
New Shipment for Guest
New Account Confirmation Key
New Account Confirmed
Newsletter Subscription Confirmation
Newsletter Subscription Success
Newsletter Unsubscribe Success
Order Update For Guest
RMA Admin Comments
RMA Admin Comments for Guest
RMA Authorization for Guest
RMA Customer Comments
Rewards Points Balance Update
Rewards Points Expiry Warning
Send Product to a Friend
Share Wish List
Shipment Update for Guest
Store Credit Update
- Click Emarsys Events to display the list of Emarsys external events and their IDs. This list will be empty the first time you open it.
- Click Update Schema to fill the list with Emarsys events.
- To add an Emarsys event to the list, open your Emarsys account and go to Automation > External Events.
- Create your external event there. It is a good idea to name it as closely as possible to the Magento event you will match it to.
- Back in your Magento account, click Update Schema to refresh the list. Your new Emarsys event should now be visible.
- Click Event Mapping to map the Magento events with their Emarsys counterparts.
- For each Magento event that you want to map, select the corresponding Emarsys event from the drop-down.
- Click Save Mapping to save your configuration.
- If you are unsure about which events to map, click Recommended Mapping. This will try to find the right Emarsys events based on their names.
Emarsys event mapping is one-to-one per website. This means that if you have multiple stores in your Magento account, you will need to map each one separately.
3. Personalizing your email content
Since your Magento contacts are synchronized with Emarsys, you can of course include in your email content all the regular personalization variables available in the Emarsys application, including conditional content and section targeting. However, there may be important information about the event that triggers the email 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 Emarsys 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.
4. Map the placeholders
Once you know which placeholders are being used in which emails, and you have mapped the corresponding events, you need to map the Magento variables with the Emarsys placeholders. You will need to do this for each Magento event.
- On the Magento Emarsys Event Mapping page, click Placeholders next to the event in question.
- For each Magento variable, add the corresponding Emarsys placeholder.
- Click Save Mapping.
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. 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.
6. Activate the transactional campaigns
Once you have mapped your events and fields, check that your email campaigns are correctly configured in Emarsys.
- In your Emarsys account, for each campaign open the Email Settings. Make sure that the Recipient source is set to Generated through an event and then select the appropriate external event.
- In the Campaign Scheduling, make sure this is set to launch Exactly on event.
In your Magento account, go to System Configuration and from the left menu select Customer Configuration.
- For each of the available options you can define a transactional email. In this example we will look at Create New Account Options, which has three welcome emails as part of a double opt-in registration process.
- Under Default Welcome Emails, select the template you want to use and click Save Config.
- Repeat this step for the Confirmation Link Email and the Welcome Email.
Now the Emarsys email campaigns associated with the template will trigger every time the corresponding trigger is activated in Magento.
7. Enable transactional messages
When you have finished your mapping, go to System > Configuration > Emarsys Connect > Transactional Mail setup and enable this functionality.
- In the Enable Emarsys transactional mails drop-down, select Yes.
- Click Save Config to save the settings.
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 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 module. All your settings and configurations will not be affected.
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.
Exporting contact data
When you try to manually synchronize contact data fields and the export gets stuck, you should first check that your cron settings are ok. If they look correct, then flush the Magento 1 cache entirely.
Inconsistent session data in Emarsys
When testing the integration (or after), you find that data is being attributed to the wrong session or contact, it may be that your Web Extend is being cached. You should open the Web Extend settings (System menu > Configuration > Emarsys Connect > Web Extend) and make sure that the Use Ajax Update or Use jQuery options are enabled, as appropriate.