Versions Compared

Version Old Version 15 New Version 16
Changes made by

Zsolt Mannheim

Zsolt Mannheim

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
stylenone

...

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.

Installation

Install via Composer

The module can be installed using Composer with the following command:

...

Stores -> Configuration -> Maileon

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.

...

  • Maileon Api Key: The API key associated with the Maileon account you wish to use. At Maileon Settings → API Keys.

Subscriber Settings

...

  • ActiveEnable: 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 GermanyThe contact will not receive newsletters.

    • Single Opt-in: Consent only given oncePermission was simply granted, e.g. by entering the an email address on the registration in a form. This method technically allows the contact to receive newsletters, but does not guarantee ensure that the subscriber is indeed identical with the email account owneremail address belongs to the person who entered it.

    • 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 externallyWith this permission, a confirmation email with a confirmation link is sent to the email address. Only when the link in the mail has been clicked and thus the interest in the entry has been confirmed, the contact can be sent.

    • Double Opt-in Plus:Double - opt-in including consent to for single user tracking.

    DOI

    • Please note: Without individual user tracking, no openings, clicks, etc. may be traced back to individual users and significant data for evaluating newsletter performance is missing.

  • Double Opt-in 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.

  • Double Opt-In Plus (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 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 Webhook 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 webhook setup will be detailed later.

  • Doi Hook DOI Confirmation Webhook 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 webhook setup will be detailed later.

  • Unsubscribe All Matching Emails: Since Magento 2.4, an the same email address can be registered subscribed 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 emailacross different store views. In Maileon, contacts may belong to different newsletter accounts per store view, so Magento needs the store view ID to unsubscribe a specific contact correctly.
    If the storeview_id is missing:

    • Yes: all Maileon contacts with the matching email will be unsubscribed.

    • No: the unsubscription will be ignored. It is recommended to configure proper store view ID passing and/or enable this option.

  • Disable Newsletter Confirmation Request Email: Disable Magento's built-in newsletter confirmation request email for newsletter subscriptions.

  • Disable Newsletter Subscription Success Email: Disable Magento's default newsletter subscription success email sent after newsletter subscription confirmation.

  • Disable Ensubscription Email: Disable Magento's default email sent when a customer unsubscribes from the newsletter.

Order Confirmation Settings

...

  • ActiveEnabled: 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.

  • Disable Order Confirmation Email: Disable Magento's default order confirmation email sent after a successful checkout.

  • Enable Separate Permission For Buyers: Enable a separate permission for buyers: If level for customers who complete a purchase, 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 permissionPermission: 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

...

Customer Related Email Notification settings

...

  • Customer credentials changed Credentials Changed (password Password and/or emailEmail): 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 reminderDisable Customer Credentials Changed Email: Disable Magento's default customer credentials changed email.

  • 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 confirmationDisable Password Reminder Email: Disable Magento's default password reminder email.

  • 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 accountDisable Password Reset Email: Disable Magento's default password reset email.

  • New Account Notification: 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

  • Disable New Account Email: Disable Magento's default new account email.

Transaction type magento_account_credentials_changed_v1

...

Order Related Email Notification Settings

...

  • Payment status changeStatus 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

  • Disable Payment Status Change Email: Disable Magento's default payment status changed email.

  • 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_v1Order status change: If this option

  • Disable Invoice Created Email: Disable Magento's default invoice created email.

  • 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

  • Disable Order Status Changed Email: Disable Magento's default order status changed email.

  • Shipment status changeStatus 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

  • Disable Shipment Status Changed Email: Disable Magento's default shipment status changed email.

Transaction types magento_order_creditmemo_v1 , magento_order_creditmemo_update_v1

...

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

Abandoned Cart Settings

...

  • ActiveEnabled: 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.

...

Field name

Type

Description

cart.id

string

The cart id (quote id)

cart.date

timestamp

The cart last updated timestamp

cart.items

JSON

Cart items

cart.product_ids

string

Cart items product ids in a list

cart.categories

string

Cart items product category names in a list

cart.total

float

Cart grand total

cart.total_tax

float

Cart tax amount

cart.currency

string

Cart currency

customer.salutation

string

Customer salutation

customer.full_name

string

Customer full name

customer.firstname

string

Customer first name

customer.lastname

string

Customer last name

customer.id

string

Customer id

generic.string_1

string

Store ID

generic.string_2

string

Store name

Configuring Custom Forms

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

...

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.

...

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

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”.

...

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

...

Changelog

2025.05.15 - v1.10.0

  • Contact events are now reliably sent to Maileon whenever Magento sends a transactional email (order, invoice etc.).

  • Email sending logic now supports separate enable/disable toggles for each type (order, invoice, shipment, etc.).

  • Complete internal refactoring of the module for improved maintainability and code quality.

  • Replaced all method overrides with Magento event-based architecture where possible.

  • Refactored newsletter subscription handling to eliminate deprecated loadByEmail() usage.

  • Removed direct use of ObjectManager in favor of dependency injection.

2025.04.08 - v1.9.6

  • Added store_id and store_name as generic fields to order confirmation and abandoned cart transactions

...