Current version: v1.9.0

...

The module synchronizes customer data, order data and shopping cart information between Magento and Maileon. Magento is the primary system, which means that the customer information in Magento is considered the main information and changes to that data are synchronized with Magento. Conversely, only certain information is synchronized: the DOI confirmation and unsubscription. For order details and cart abandonments, this information is sent to Maileon as transactions (events) and can be used either to analyze data using contact filters or to activate a trigger mailing. All functions can be set via a configuration panel in Magento.

Install the Module

Below version 1.0.8

The first step is to copy the Maileon directory into the /app/code directory of the Magento installation. If the app directory doesn't already contain a code subdirectory please create it. After this the module must be enabled using the following steps:

...

php bin/magento setup:upgrade

Configuration in Magento

The configuration can be found under “Stores” “Configuration” and, since version 1.8, can be set on Storeview level. This means, that for each Storeview, you can select an own API key, to use different Maileon accounts or you can select different DOI mail keys to send out DOIs in e.g. different languages.

...

• Active: This enables the order confirmation module. This module synchronizes order events to Maileon. Each order creates two types of transactions: magento_orders_v2 and magento_orders_extended_v2. The transaction magento_orders_v2 contains one event for each order. The transaction magento_orders_extended_v2 contains one event per line item in the order.

• Enable separate permission for buyers: If this setting is enabled, customers who do not yet exist in Maileon and have not unsubscribed will be created with the permission set below. They will be granted instant permission even if the permission are DOI or DOI+

• Buyers permission: If the above option is enabled, you can set the permission here

Transaction type magento_orders_v2

...

Field name

...

Type

...

Description

...

After version 1.9 you do not need to disable Magento order confirmation emails in the settings. (Configuration/Sales/Sales Emails → Order)

Transaction type magento_orders_v2

Transaction type magento_orders_v2 order.items

Transaction type magento_orders_extended_v2

Customer Related Email Notification settings

...

Transaction type magento_account_credentials_changed_v1

Abandoned Cart Settings

Image Removed

Figure 7: Shopping Cart Abandonnment Mail Settings

• Active: This enables the cart abandonment module. This module synchronizes abandoned cart events to Maileon.

• Fallback permission: the permission a contact will get when added to Maileon. This should be set to none in most cases.

• # Of Hours Before Sending Reminder: This is the number of hours after an open cart is considered abandoned.

• Shadow Email: This email address also receives a copy of the cart abandonment email.

• Email Override: If this field is set customers won’t receive cart abandonment emails. This address will receive them instead.

...

Figure 8: Transactiontype for Cart Abandonnments

Configuring Custom Forms

In order to submit other standard or custom data to Maileon, the following scheme must be used:

• Standard fields: The standard fields must use the prefix standard_, followed by the exact name and providing the correct format, documented on http://dev.maileon.com/api/rest-api-1-0/contacts/standard-contact-fields/
  Example: standard_FIRSTNAME

• Custom fields: I custom fields should be submitted, they need to have the prefix custom_. Capizalization needs to be respected exactly as specified in Maileon.

Example: custom_MySpecialField

Enhancing Transactional Data

In some cases, it is required to add custom data transactions. E.g. if you use a plugin, which allows customizing products with names, custom images, etc., and the image shall be displayed in the order confirmation mail, you need to pass this URL to Maileon. Or this case, the plugin provides a simple way to add data to the transactions by overriding class “Maileon\SyncPlugin\Helper\External\Data” from an external plugin.

To ease development, we provide a test plugin that shows a minimalistic setup. In di.xml, the class is overwritten with an own implementation:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

<preference for="Maileon\SyncPlugin\Helper\External\Data" type="Maileon\TestPlugin\Helper\External\Data" />

</config>

Investigating class “Maileon\TestPlugin\Helper\External\Data”, which is provided by the test package and can be also named freely, there are different methods that can be used.

This method adds attributes to a single product within an order. Based on the product, e.g. a URL of a custom image could be retrieved and returned in the array:
getCustomProductAttributes($product)

This method adds attributes to an order, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition¹:

getCustomOrderTransactionAttributes($transaction_content)

This method adds attributes to single item transactions, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition²:

getCustomOrderExtendedTransactionAttributes($transaction_ext_content)

Transaction type magento_password_reminder_v1

Transaction type magento_password_reset_confirmation_v1

Transaction type magento_new_account_v1

Order Related Email Notification Settings

...

• Payment status change: If this option is enabled, it will send a transaction to Maileon in cases when a credit memo is created or updated for the order. Transaction type: magento_order_creditmemo_v1 , magento_order_creditmemo_update_v1

• Invoice: If this option is enabled, it will send a transaction to Maileon in cases when a invoice is created or updated for the order. Transaction type: magento_order_invoice_v1 , magento_order_invoice_update_v1

• Order status change: If this option is enabled, it will send a transaction to Maileon in cases when the order status changed. Transaction type: magento_order_status_changed_v1

• Shipment status change: If this option is enabled, it will send a transaction to Maileon in cases when a shipment is created or updated for the order. Transaction type: magento_order_shipment_v1 , magento_order_shipment_update_v1

Transaction types magento_order_creditmemo_v1 , magento_order_creditmemo_update_v1

Transaction types magento_order_invoice_v1 , magento_order_invoice_update_v1

Transaction type magento_order_status_changed_v1

Transaction types magento_order_shipment_v1 , magento_order_shipment_update_v1

order.items json content

Abandoned Cart Settings

Image Added

• Active: This enables the cart abandonment module. This module synchronizes abandoned cart events to Maileon.

• Fallback permission: the permission a contact will get when added to Maileon. This should be set to none in most cases.

• # Of Hours Before Sending Reminder: This is the number of hours after an open cart is considered abandoned.

• Shadow Email: This email address also receives a copy of the cart abandonment email.

• Email Override: If this field is set customers won’t receive cart abandonment emails. This address will receive them instead.

• Test Webhook Active: If this field is enabled, the corresponding API endpoint can be used for testing purposes.

• Test Webhook Token: If the above field is enabled, the test API endpoint can be protected with this token.

Transaction type magento_abandoned_carts_v2

Configuring Custom Forms

In order to submit other standard or custom data to Maileon, the following scheme must be used:

• Standard fields: The standard fields must use the prefix standard_, followed by the exact name and providing the correct format, documented on http://dev.maileon.com/api/rest-api-1-0/contacts/standard-contact-fields/
  Example: standard_FIRSTNAME

• Custom fields: I custom fields should be submitted, they need to have the prefix custom_. Capitalization needs to be respected exactly as specified in Maileon.

Example: custom_MySpecialField

Enhancing Transactional Data

In some cases, it is required to add custom data transactions. E.g. if you use a plugin, which allows customizing products with names, custom images, etc., and the image shall be displayed in the order confirmation mail, you need to pass this URL to Maileon. Or this case, the plugin provides a simple way to add data to the transactions by overriding class Maileon\SyncPlugin\Helper\External\Data from an external plugin.

To ease development, we provide a test plugin that shows a minimalistic setup. In di.xml, the class is overwritten with an own implementation:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <preference for="Maileon\SyncPlugin\Helper\External\Data" type="Maileon\TestPlugin\Helper\External\Data" />

</config>

Investigating class Maileon\TestPlugin\Helper\External\Data, which is provided by the test package and can be also named freely, there are different methods that can be used.

• This method adds attributes to a single product within an

...

• order. Based on the product, e.g. a URL of a custom image could be retrieved and returned in the array:
  

...

• getCustomProductAttributes($product)
  

• This method adds attributes to

...

• an order, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition

...

• ¹:
  

...

• getCustomOrderTransactionAttributes($transaction_content)
  

The data can be added e.g. by writing it to one of the free generic string fields:

$result['generic.string_1'] = "this is an additional information";

This value can then be used in a mailing to print it, use it as a link or an image URL.

The installation of the plugin is as expected done by using Composer. The first step is to copy the ‘Maileon’ directory of the test plugin into the /app/code directory of the Magento installation. If the app directory doesn’t already contain a code subdirectory please create it. After this the module must be enabled using the following steps:

...

• This method adds attributes to single item transactions, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition²:
  getCustomOrderExtendedTransactionAttributes($transaction_ext_content)

• This method adds attributes to a single product within an card abandonment transaction. Based on the product, e.g. a URL of a custom image could be retrieved and returned in the array:
  getCustomAbandonedCartProductAttributes($product)

• This method adds attributes to a cart abandonment transaction, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition³:
  getCustomAbandonedCartTransactionAttributes($transaction_content)

• The data can be added e.g. by writing it to one of the free generic string fields:
  $result['generic.string_1'] = "this is an additional information";

This value can then be used in a mailing to print it, use it as a link or an image URL.

The installation of the plugin is as expected done by using Composer. Install in the same way as the current plugin (see above)

If everything was installed as expected, the next time e.g. an order is triggered, some additional data should be attached to it.

Image Modified

...

Webhook Settings in Maileon

Changed parameters in version 1.8:
Since Magento 2.4, an email can be added as newsletter subscriber for each storeview, thus, the email can exist multiple times in the Magento newsletter module. As of version 1.8 of the plugin, configuration is based on storeview level, thus, an email can be added to different Maileon newsletter accounts based on its origin. Thus, when Maileon reports back a DOI confirmation or unsubscription, it needs to identify the correct storeview for a given contact. This is done by adding a new parameter “storeview_id”.

Unsubscription Webhook Setup

The unsubscription webhook is used to synchronize Maileon unsubscribers back to Magento. To set this up in Maileon you must navigate to Settings/Webhooks. In this panel click Create new webhook. Select Unsubscription from the event dropdown. Enter the following for HTTP post URL (substituting your own domain):

...

https://<my domain>/rest/V1/maileon/webhook-unsubscribe

e.g.:

...

https://maileonmagento.com/rest/V1/maileon/webhook-unsubscribe

Add the following URL parameters:

• email -> contact field value -> E-mail address

• token -> user-defined value -> <token>

• storeview_id -> contact field value -> magento_storeview_id

...

Figure 10: Webhook Settings for Unsubscriptions

Please note: To now anonymize the contact field “magento_storeview_id” in case of an unsubscription, it is required to configure Maileon accordingly.

DOI Confirmation Webhook Setup

The DOI confirmation webhook is used to synchronize Maileon DOI confirmations back to Magento. To set this up in Maileon you must navigate to Settings/Webhooks. In this panel click Create new webhook. Select DOI Confirmation from the event dropdown. Enter the following for HTTP post URL (substituting your own domain):

...

https://<my domain>/rest/V1/maileon/webhook-doi

...

-confirm

eg.:

...

https://maileonmagento.com/rest/V1/maileon/webhook-doi

...

-confirm

Add the following URL parameters:

• email -> contact field value -> E-mail address

• token -> user-defined value -> <token>

• storeview_id -> contact field value -> magento_storeview_id

The token must match the value given for the DOI Hook Token given in Magento settings.

...

Figure 11: Webhook Settings for DOI-Confirmations

Changelog

...

Changelog

2023.06.14 - v 1.9.0

• Add customer account related transactions

• Add order related transactions

• Improve abandoned carts functionality

2023.04.06 - v 1.8.12

• Bugfix: AfterPlaceOrder product categories

2022.12.06 - v 1.8.11

• Abandoned cart work with storeviews

2022.10.25 - v 1.8.10

• Update Maileon Php API client minimum version

2022.08.30 – v 1.8.9

• Added payment method ID and name to order transactions

132022.05.2022 13 – v 1.8.8

• Enhancing of loading images in abandoned carts when model is not initialized in cron job, yet

112022.05.2022 11 – v 1.8.7

• Change in URLs for images inside abandoned cart transactions

• Compatibility fix for 2.4.4

252022.01.2022 25 – v 1.8.6

• Changing DB table creation to declarative model

182022.01.2022 18 – v 1.8.5

• Added thumbnail to abandoned carts transaction

192021.11.2021 19 – v 1.8.4.1

• Added description about how to enable Maileon to send contactfield storeview_id to the Magento webhook when unsubscribing

172021.11.2021 17 – v 1.8.4

• Fixed users getting redirected to blank page after subscribing in some Magento versions

• Fixed error message when specifying wrong storeview ID in webhooks

• Added configuration for testing abandoned carts

132021.09.2021 13 – v 1.8.3

• Add functionality to add separate Maileon permission for buyers

102021.09.2021 10 – v 1.8.2

• Resubscribe with same email address fix

132021.07.2021 13 – v 1.8.1

• Recreate the package to work with composer

2021.07.07 .2021 – v 1.8

• Plugin configuration extended to storeview level

• Add extra parameter to DOI confirmation and unsubscribe webhook to identify the correct storeview

• Add a custom field to contact: magento_storeview_id

• Add a custom field to contact: magento_source

• Renamed plugin from Maileon_SyncPlugin to Xqueue_Maileon in order to match marketplace requirements. Manual deinstallation and reinstallation needed for updating. Configuration will be kept.

042021.02.2021 04 – v 1.7

• Updated subscriber logic to support “initial” and “target” permission separately

272021.01.2021 27 – v 1.6

• Added new settings for fallback permissions for orders and cart abandonments

152021.01.2021 15 – v 1.5

• Added new Maileon webhooks API URLs, to process DOI confirm and unsubscribe webhooks

• Bugfix at abandoned carts methods in case of exceptions

• Add new fields to order transactions and round the float values to two digits

242020.11.2020 24 – v 1.4

• Added overwritable class for enriching transactions with custom data

• Switching to default transaction type definitions defined at https://dev.maileon.com/api/implementation-guideline/implementation-guidelines-transactions/

• Fixing warning about deprecated syntax in Maileon API client

References

¹ https://dev.maileon.com/api/implementation-guideline/implementation-guidelines-transactions/implementation-guidelines-order-confirmation/

...