Current version: v1.9.0

Introduction

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:

From version 1.8.1

Copy the Maileon plugin to the Magento root folder (/sources/magento-2/Xqueue/Maileon/). Add the following line to the Magento composer.json:

"require": {
    "xqueue/module-maileon": "^1.8"
},

"repositories": [
    {
        "type": "composer",
        "url": "https://repo.magento.com/"
    },
    {
        "name": "xqueue/module-maileon",
        "type": "path",
        "url": "sources/magento-2/Xqueue/Maileon"
    }
],

Run composer update at command line

Enable the module

Before enable the module, we must check to make sure Magento has recognize our module or not by enter the following at the command line:

php bin/magento module:status

If you follow above step, you will see this in the result:

List of disabled modules:
Xqueue_Maileon

This means the module has recognized by the system but it is still disabled. Run this command to enable it:

php bin/magento module:enable Xqueue_Maileon

If the above succeeded the following message is displayed:

The following modules has been enabled:
Xqueue_Maileon

This’s the first time you enable this module so Magento require to check and upgrade module database. We need to run this command:

php bin/magento setup:upgrade

If everything went well you can switch to Magento’s admin interface. The plugin settings are available in the following menu:

Stores -> Configuration -> Maileon

Update the Module

Copy the contents of the new version package to /sources/magento-2/Xqueue/Maileon/

Run composer update at command line

To update database schema and dependencies, run this command:

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.

Figure 1: Plugin Settings

General Settings

Figure 2: General settings

Maileon Api Key: The API key associated with the Maileon account you wish to use.
Print CURL Debug Data: Enabling this will show Maileon API responses. Useful for debugging. Not to be used in a live environment!

Subscriber Settings

Active: This enables the newsletter subscriber module. This module synchronizes new subscriptions to Maileon.
Initial Permission: The initial permission level to set for new Maileon subscribers.
- None: No permission. This is most likely what is required, e.g. in Germany.
- Single Opt-in: Consent only given once, e.g. by entering the email address on the registration form. This does not guarantee that the subscriber is indeed identical with the email account owner.
- Confirmed Opt-in: A confirmation mail about the registration is sent to the provided email address, but it does not contain a confirmation link. This method is frequently abused by spammers. The recipient will have to actively revoke consent in order not to receive any advertising emails. This method is not really legal in Germany and should not be used.
- Double Opt-in: Set double-opt-in in Maileon, e.g. if such a permission has already been gathered externally.
- Double Opt-in Plus: Double-opt-in including consent to single user tracking.
DOI Process: A confirmation email including a “confirmation link” is sent to the provided email address. The subscription will not be valid until the recipient clicks this link. Thus it is ensured that the recipient is identical to the mailbox owner and really wishes to receive your emailings (the recipient cannot click the confirmation link without having signed in to her or his mailbox). Double Opt-in is the only subscription method we can recommend. Please note that XQ can only provide general information but no official legal counselling. Please contact your lawyer in the case of legal questions on this topic.
DOI+ Process: Requires option “DOI Process”. A DOI+ permission will be registered after the user clicks the DOI confirmation link in the DOI mail.

Please note: You can only obtain significant response analyses and react appropriately when your contacts have given consent to single user tracking. Taking into account that only the double-opt-in procedure is legally safe (for German-based providers), the only permission method we can recommend is “Double Opt-in including consent to single user tracking”.

Doi Mailing ID: If the permission above is set to DOI or DOI-Plus the newsletter subscriber will be sent a confirmation mailing using Maileon. This field can be used to customize which DOI mailing will be sent from Maileon. Leaving it empty means that the default DOI confirmation will be sent. (A default DOI confirmation mailing must be set in Maileon in order for this to work.)
Unsubscribe Hook Token: This token is used to synchronize Maileon unsubscribers back to Magento. This field must be a unique string. (Think of it as a password.) The hook setup will be detailed later.
Doi Hook Token: This token is used to synchronize Maileon DOI confirmations back to Magento. If set the Magento subscriber state will match the Maileon subscription state of each customer. This field must be a unique string. (Think of it as a password.) The hook setup will be detailed later.
Unsubscribe All Emails: Since Magento 2.4, an email can be registered multiple times with Magento (one time for each storeview). When Maileon reports back unsubscribers to Magento it passes along the storeview ID but if that data gets deleted or is not added in the webhook configuration, Magento does not know from which storeview to unsubscribe the contact of. This option allows to unsubscribe all contacts with a given email address (from all storeviews) if ambiguous or if required (e.g. by law).
Disable confirmation request email: Used to disable the built-in Magento DOI confirmation email.
Disable success email: Used to disable the built-in Magento DOI success email.
Disable unsubscription email: Used to disable the built-in Magento unsubscriber email.

Order Confirmation Settings

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

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`

Field name	Type	Description

Field name	Type	Description
`order.id`	string	Order id (incremental id)
`order.date`	timestamp	Order timestamp
`order.status`	string	Order status
`order.total`	float	Order grand total
`order.total_tax`	float	Order tax amount
`order.total_no_shipping`	float	Order total without shipping cost
`order.currency`	string	Order currency
`shipping.service.name`	string	Shipping method
`payment.method.id`	string	Payment id
`payment.method.name`	string	Payment name
`order.items`	JSON	Ordered items in json
`shipping.address.firstname`	string	Shipping address first name
`shipping.address.lastname`	string	Shipping address last name
`shipping.address.phone`	string	Shipping address phone
`shipping.address.region`	string	Shipping address region
`shipping.address.city`	string	Shipping address city
`shipping.address.zip`	string	Shipping address zip
`shipping.address.street`	string	Shipping address street
`billing.address.firstname`	string	Billing address first name
`billing.address.lastname`	string	Billing address last name
`billing.address.phone`	string	Billing address phone
`billing.address.region`	string	Billing address region
`billing.address.city`	string	Billing address city
`billing.address.zip`	string	Billing address zip
`billing.address.street`	string	Billing address street

Transaction type `magento_orders_v2` `order.items`

Field name	Type	Description

Field name	Type	Description
`product_id`	string	Product id
`title`	string	Product title
`single_price`	float	Product single price
`total`	float	Item total price
`sku`	string	Product sku
`quantity`	integer	Item quantity
`url`	string	Product url
`image_url`	string	Product image url
`categories`	string	Product categories list separated with ,
`short_description`	string	Product short description

Transaction type `magento_orders_extended_v2`

Field name	Type	Description

Field name	Type	Description
`order.id`	string	Order id (incremental id)
`order.date`	timestamp	Order timestamp
`order.status`	string	Order status
`order.total`	float	Order grand total
`order.total_tax`	float	Order tax amount
`order.total_no_shipping`	float	Order total without shipping cost
`order.currency`	string	Order currency
`shipping.service.name`	string	Shipping method
`payment.method.id`	string	Payment id
`payment.method.name`	string	Payment name
`product.id`	string	Product id
`product.title`	string	Product title
`product.single_price`	float	Product single price
`product.total`	float	Item total price
`product.sku`	string	Product sku
`product.quantity`	integer	Item quantity
`product.image_url`	string	Product image url
`product.url`	string	Product url
`product.categories`	string	Product categories list separated with ,
`product.short_description`	string	Product short description
`shipping.address.firstname`	string	Shipping address first name
`shipping.address.lastname`	string	Shipping address last name
`shipping.address.phone`	string	Shipping address phone
`shipping.address.region`	string	Shipping address region
`shipping.address.city`	string	Shipping address city
`shipping.address.zip`	string	Shipping address zip
`shipping.address.street`	string	Shipping address street
`billing.address.firstname`	string	Billing address first name
`billing.address.lastname`	string	Billing address last name
`billing.address.phone`	string	Billing address phone
`billing.address.region`	string	Billing address region
`billing.address.city`	string	Billing address city
`billing.address.zip`	string	Billing address zip
`billing.address.street`	string	Billing address street

Customer Related Email Notification settings

Customer credentials changed (password and/or email): If this option is enabled, it will send a transaction to Maileon in cases where the customer changes their email address and/or password. Transaction type: magento_account_credentials_changed_v1
Customer password reminder: If this option is enabled, it will send a transaction to Maileon in case when the customer wants a password reminder. Transaction type: magento_password_reminder_v1
Customer password reset confirmation: If this option is enabled, it will send a transaction to Maileon in case when the customer wants a password reset. Transaction type: magento_password_reset_confirmation_v1
New account: If this option is enabled, it will send a transaction to Maileon in case when the customer create a new account. If Magento is configured to confirm the email address when creating a new account, it sends an email address confirmation notification, if not, it sends a welcome notification Transaction type: magento_new_account_v1

Transaction type `magento_account_credentials_changed_v1`

Field name	Type	Description

Field name	Type	Description
`fullname`	string	Customer full name
`changed_field`	string	The changed field name (email, password)
`store_id`	string	Store id
`store_name`	string	Store name
`store_email`	string	Store email address
`store_phone`	string	Store phone

Transaction type `magento_password_reminder_v1`

Field name	Type	Description

Field name	Type	Description
`fullname`	string	Customer full name
`account_url`	string	Customer account url
`psw_reset_url`	string	Customer password reset url
`store_id`	string	Store id
`store_name`	string	Store name

Transaction type `magento_password_reset_confirmation_v1`

Field name	Type	Description

Field name	Type	Description
`fullname`	string	Customer full name
`psw_reset_url`	string	Customer password reset url
`store_id`	string	Store id
`store_name`	string	Store name

Transaction type `magento_new_account_v1`

Field name	Type	Description

Field name	Type	Description
`fullname`	string	Customer full name
`type`	string	Notification type: `customer/create_account/email_template` : welcome email, when confirmation is disabled and password is set `customer/create_account/email_no_password_template` : welcome email, when confirmation is disabled and password is not set `customer/create_account/email_confirmation_template` : welcome email, when confirmation is enabled and password is set `customer/create_account/email_confirmed_template` : email with confirmation link
`account_url`	string	Customer account url
`account_confirm_url`	string	Customer account confirmation url
`psw_reset_url`	string	Customer password reset url
`store_id`	string	Store id
`store_name`	string	Store name

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`

Field name	Type	Description

Field name	Type	Description
`order.id`	string	Order id (incremental id)
`order.date`	timestamp	Order timestamp
`order.status`	string	Order status
`order.total`	float	Order grand total
`order.total_tax`	float	Order tax amount
`order.total_no_shipping`	float	Order total without shipping cost
`order.currency`	string	Order currency
`shipping.service.name`	string	Shipping method
`payment.method.id`	string	Payment id
`payment.method.name`	string	Payment name
`order.items`	JSON	Ordered items in json
`shipping.address.firstname`	string	Shipping address first name
`shipping.address.lastname`	string	Shipping address last name
`shipping.address.phone`	string	Shipping address phone
`shipping.address.region`	string	Shipping address region
`shipping.address.city`	string	Shipping address city
`shipping.address.zip`	string	Shipping address zip
`shipping.address.street`	string	Shipping address street
`billing.address.firstname`	string	Billing address first name
`billing.address.lastname`	string	Billing address last name
`billing.address.phone`	string	Billing address phone
`billing.address.region`	string	Billing address region
`billing.address.city`	string	Billing address city
`billing.address.zip`	string	Billing address zip
`billing.address.street`	string	Billing address street
`order.creditmemo.id`	string	Order credit memo id
`order.comment`	string	Order comment
`store.id`	string	Store id
`store.name`	string	Store name

Transaction types `magento_order_invoice_v1` , `magento_order_invoice_update_v1`

Field name	Type	Description

Field name	Type	Description
`order.id`	string	Order id (incremental id)
`order.date`	timestamp	Order timestamp
`order.status`	string	Order status
`order.total`	float	Order grand total
`order.total_tax`	float	Order tax amount
`order.total_no_shipping`	float	Order total without shipping cost
`order.currency`	string	Order currency
`shipping.service.name`	string	Shipping method
`payment.method.id`	string	Payment id
`payment.method.name`	string	Payment name
`order.items`	JSON	Ordered items in json
`shipping.address.firstname`	string	Shipping address first name
`shipping.address.lastname`	string	Shipping address last name
`shipping.address.phone`	string	Shipping address phone
`shipping.address.region`	string	Shipping address region
`shipping.address.city`	string	Shipping address city
`shipping.address.zip`	string	Shipping address zip
`shipping.address.street`	string	Shipping address street
`billing.address.firstname`	string	Billing address first name
`billing.address.lastname`	string	Billing address last name
`billing.address.phone`	string	Billing address phone
`billing.address.region`	string	Billing address region
`billing.address.city`	string	Billing address city
`billing.address.zip`	string	Billing address zip
`billing.address.street`	string	Billing address street
`order.invoice.id`	string	Order invoice id
`order.comment`	string	Order comment
`store.id`	string	Store id
`store.name`	string	Store name

Transaction type `magento_order_status_changed_v1`

Field name	Type	Description

Field name	Type	Description
`order.id`	string	Order id (incremental id)
`order.date`	timestamp	Order timestamp
`order.status`	string	Order status
`order.total`	float	Order grand total
`order.total_tax`	float	Order tax amount
`order.total_no_shipping`	float	Order total without shipping cost
`order.currency`	string	Order currency
`shipping.service.name`	string	Shipping method
`payment.method.id`	string	Payment id
`payment.method.name`	string	Payment name
`order.items`	JSON	Ordered items in json
`shipping.address.firstname`	string	Shipping address first name
`shipping.address.lastname`	string	Shipping address last name
`shipping.address.phone`	string	Shipping address phone
`shipping.address.region`	string	Shipping address region
`shipping.address.city`	string	Shipping address city
`shipping.address.zip`	string	Shipping address zip
`shipping.address.street`	string	Shipping address street
`billing.address.firstname`	string	Billing address first name
`billing.address.lastname`	string	Billing address last name
`billing.address.phone`	string	Billing address phone
`billing.address.region`	string	Billing address region
`billing.address.city`	string	Billing address city
`billing.address.zip`	string	Billing address zip
`billing.address.street`	string	Billing address street
`order.comment`	string	Order comment
`store.id`	string	Store id
`store.name`	string	Store name

Transaction types `magento_order_shipment_v1` , `magento_order_shipment_update_v1`

Field name	Type	Description

Field name	Type	Description
`order.id`	string	Order id (incremental id)
`order.date`	timestamp	Order timestamp
`order.status`	string	Order status
`order.total`	float	Order grand total
`order.total_tax`	float	Order tax amount
`order.total_no_shipping`	float	Order total without shipping cost
`order.currency`	string	Order currency
`shipping.service.name`	string	Shipping method
`payment.method.id`	string	Payment id
`payment.method.name`	string	Payment name
`order.items`	JSON	Ordered items in json
`shipping.address.firstname`	string	Shipping address first name
`shipping.address.lastname`	string	Shipping address last name
`shipping.address.phone`	string	Shipping address phone
`shipping.address.region`	string	Shipping address region
`shipping.address.city`	string	Shipping address city
`shipping.address.zip`	string	Shipping address zip
`shipping.address.street`	string	Shipping address street
`billing.address.firstname`	string	Billing address first name
`billing.address.lastname`	string	Billing address last name
`billing.address.phone`	string	Billing address phone
`billing.address.region`	string	Billing address region
`billing.address.city`	string	Billing address city
`billing.address.zip`	string	Billing address zip
`billing.address.street`	string	Billing address street
`order.shipment.id`	string	Order shipment id
`order.comment`	string	Order comment
`store.id`	string	Store id
`store.name`	string	Store name
`shipping.service.id`	string	Carrier code
`shipping.service.tracking.url`	string	Tracking popup url
`shipping.service.tracking.code`	string	Tracking code

`order.items` json content

Field name	Type	Description

Magento 2

Introduction

Install the Module

Below version 1.0.8

From version 1.8.1

Enable the module

Update the Module

Configuration in Magento

General Settings

Subscriber Settings

Order Confirmation Settings

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

Transaction type magento_password_reminder_v1

Transaction type magento_password_reset_confirmation_v1

Transaction type magento_new_account_v1