1 Release notes
2 Introduction
3 Installation and preparation
- 3.1 Check requirements
- 3.2 Install module
  - 3.2.1 1. From the Shopware Plugin Store (recommended)
  - 3.2.2 2. Install .zip package manually
- 3.3 Configure module
  - 3.3.1 Send subscribers to Maileon:
  - 3.3.2 Maileon API Key:
  - 3.3.3 Initial permission:
  - 3.3.4 Enable DOI process:
  - 3.3.5 Enable DOI+ (single user tracking in Maileon):
  - 3.3.6 DOI key for guests:
  - 3.3.7 DOI key for registered customers:
  - 3.3.8 Send transaction emails from Shopware:
  - 3.3.9 Send DOI mails from Shopware:
  - 3.3.10 Maileon API Timeout:
  - 3.3.11 Maileon API key for transactions:
  - 3.3.12 Send order information to Maileon:
  - 3.3.13 Send one additional event per ordered product:
  - 3.3.14 Additionally use old transaction types:
  - 3.3.15 Product properties send in transactions:
  - 3.3.16 Automatically add buyers to newsletter:
  - 3.3.17 Buyer permission:
  - 3.3.18 Send account confirmation mails from Maileon:
  - 3.3.19 Send password reset mails from Maileon:
  - 3.3.20 Send password reset confirmation emails from Maileon:
  - 3.3.21 Send order and payment status emails from Maileon:
  - 3.3.22 Send shopping cart abandonment emails:
  - 3.3.23 Time after which a shopping cart is considered abandoned (min. 5 minutes):
  - 3.3.24 Send shopping cart abandonment emails to contacts without permission:
  - 3.3.25 Custom Contact Fields:
- 3.4 Advanced configuration and initial service
4 Transferred contact data
5 Customised forms for registration
6 Settings to be made in Maileon
- 6.1 DOI confirmations
- 6.2 Unsubscribe
7 Using the plugin from within other plugins
8 Changelog

Release notes

From version 1.4.0 the plugin is compatible with the Shopware Plugin Store. Unfortunately, the necessary changes are not backwards compatible, so that BEFORE installing version 1.4.0 or higher, all older versions up to 1.3.9 must be uninstalled manually.
From version 1.4.13, the "Update transaction types" function in the UI should be used so that the manufacturer number can also be transferred.

Introduction

The module synchronises customer data between Shopware and Maileon. Newsletter subscribers are synchronised from Shopware to Maileon and unsubscribes are transferred from Maileon to Shopware. Furthermore, transaction emails can be triggered via the backend/plugins or the API when orders change. All functions can be set via a configuration panel in Shopware.

The module is used in the XQueue example instance http://dev-shop1000.maileon.com/shopware/ (Figure 1).

Figure 1: Sample instance of Shopware 5

Installation and preparation

Check requirements

The current module was developed and tested with version 5.5 upwards. For older versions up to version 5.2, the plugin can be used in version 1.1.0 (however, all transactional emails are missing here), unfortunately the module is not suitable for older versions.

Install module

The module can be installed in two ways:

1. From the Shopware Plugin Store (recommended)

https://store.shopware.com/xqueu90114086971f/xqueue-maileon-newslettermanagement-for-shopware-5.html

The advantage of this approach is clear: easy installation and very simple information and update options.

Figure 2: Shopware Plugin Store

2. Install .zip package manually

Upload the zip package to Shopware 5 and install (Figure 3 and Figure 4).

Figure 4 shows the Plugin Manager after the module has been successfully uploaded. The module can already be configured via the red marked "Edit" button or first installed and activated via the green + symbol. Figure 5 shows the module after successful activation.

Configure module

The module now only needs to be configured by clicking on the "Edit" button.

Figure 6 shows the configuration page on which the API key and a permission must first be entered. The API key can be created and viewed in the Maileon account under "Settings" "API Keys". Since version 1.1.0, the plugin is sub/language shop-capable. In the settings, there is then a configuration for each subshop.

Send subscribers to Maileon:

If activated, subscribers to the newsletter are transferred to Maileon.

Maileon API Key:

The Maileon API key that identifies the account and access rights.

Initial permission:

None: No permission. The contact will not receive any emails.

Single Opt-in: Permission was simply granted, e.g. by entering an email address in a form. This method technically allows the contact to receive emails, but does not ensure that the email address belongs to the person who entered it.

Double Opt-in: With this permission, a confirmation email with a confirmation link is sent to the email address. Only when the link in the email has been clicked and thus the interest in the entry has been confirmed, can the contact be sent.

Double Opt-in Plus: Double Opt-in including consent to single user tracking. (Please note: Without individual user tracking, no openings, clicks, etc. may be tracked and significant data for evaluating newsletter performance is missing.)

Enable DOI process:

If a DOI mailing is to be sent from Maileon, this option must be set to "Yes".

Enable DOI+ (single user tracking in Maileon):

If, in addition to DOI, consent for single-user tracking is also to be set after the DOI confirmation link, this option must be set to "Yes". DOI+ is the basis for many evaluations on an individual user basis.

DOI key for guests:

Here you can store a DOI mailing key that determines which DOI mailing should be triggered as soon as a guest registers for the newsletter. The key can be configured or read out in Maileon for the corresponding DOI mailing.

DOI key for registered customers:

Here you can store a DOI mailing key that determines which DOI mailing should be triggered as soon as a customer registers for the newsletter. The key can be configured or read out in Maileon for the corresponding DOI mailing.

Send transaction emails from Shopware:

Here you can specify that Shopware sends the transaction emails itself.

Send DOI mails from Shopware:

Here you can specify that Shopware sends the DOI mails itself. Recommended setting: no/nein.

Maileon API Timeout:

With this field, the timeout for unsuccessful calls can be selected between 5 and 30 seconds.

Maileon API key for transactions:

Transactions can be sent via another Maileon account to avoid permission issues. If the transactions are sent via the same account, care should be taken that they are created with SOI in Maileon. Newsletters should not be sent to contacts with SOI in this case.

The following points concern transactional emails. It should be noted that transactions are automatically created the first time they are used. So if a mailing for an order confirmation is to be created, the menu item must first be activated (clear cache afterwards!), then an order can be placed. In Maileon, a transaction type is created as a confirmation on the basis of which the mailing can be created.

Send order information to Maileon:

With this option, order information is sent to Maileon. This means that order confirmation emails can be sent from Maileon or the data can be used for segmentation or marketing automation.

Transaction types:

shopware_order_confirmation_cash_in_advanced_1.0

shopware_order_confirmation_customer_1.0

shopware_order_confirmation_guest_1.0

Send one additional event per ordered product:

This option only applies if order information is generally transmitted to Maileon. One transaction is triggered per product so that segmentations are possible at the individual product level.

Transaction types:

shopware_ordered_products_2.0

Additionally use old transaction types:

Since version 1.4.15 new transaction type is used for event per ordered product. If you want to use the old transaction type (shopware_ordered_products_1.0) enable this field.

In version 1.4.15, the old transaction types have been phased out, the following is only true for versions 1.4.14 and older:
Since version 1.3.0, new transaction types are used. To ensure that existing integrations continue to work, the old types can also be transferred in addition to the new transactions until the changeover of the mailings has been completed. This option should be set to "no" for all new customers.

Product properties send in transactions:

For products where variations are available, the variation details will be included in the order per product transaction (shopware_ordered_products_2.0). Since variations can have different properties, a separate configuration interface is needed to set which variation properties should appear in which transaction fields. If this setting is enabled, you will then need to make additional settings in Maileon Manager, see: Product properties config

Automatically add buyers to newsletter:

In some situations, it may be allowed to send interest-based advertising to buyers. With this option, buyers are transferred to Maileon. Buyers who have explicitly unsubscribed from the newsletter will be ignored.

Buyer permission:

When a contact is added through a purchase and the above option is enabled, this permission is set.

Send account confirmation mails from Maileon:

Mails related to account creation and administration.

Note: depending on whether DOI is activated for account creation in Shopware, an email with a confirmation link is sent first (shopware account confirmation), otherwise the confirmation is sent immediately and the account is activated.

Transaction types:

shopware_account_change_email

shopware_account_confirmation

shopware_account_creation

Send password reset mails from Maileon:

This option allows mails with a password change link to be sent via Maileon.

Transaction type:

shopware_password_reset

Send password reset confirmation emails from Maileon:

When enabled, a confirmation email of a password change is triggered via Maileon.

Transaction type:

shopware_password_reset_confirmation

Send order and payment status emails from Maileon:

This option allows you to send a notification via Maileon when the status of the order, payment status or the status of an individual item changes.

shopware_order_confirmation_cash_in_advanced

shopware_order_confirmation_customer

shopware_order_confirmation_guest

shopware_order_status_acknowledgement_returns

shopware_order_status_cancelled

shopware_order_status_clarification_required

shopware_order_status_completed

shopware_order_status_completed_delivery_customer

shopware_order_status_completed_delivery_guest

shopware_order_status_in_process

shopware_order_status_partial_cancellation

shopware_order_status_partially_completed

shopware_order_status_partially_delivery_customer

shopware_order_status_partially_delivery_guest

shopware_order_status_ready_delivery

shopware_payment_status_completed_invoiced

shopware_payment_status_completed_paid

shopware_payment_status_delayed

shopware_payment_status_encashment

shopware_payment_status_first_reminder

shopware_payment_status_no_credit_appr

shopware_payment_status_partially_invoiced

shopware_payment_status_partially_paid

shopware_payment_status_recrediting

shopware_payment_status_review_required

shopware_payment_status_second_reminder

shopware_payment_status_third_reminder

Send shopping cart abandonment emails:

Here you define whether forgotten shopping carts should be sent to Maileon for further processing.

shopware_abandoned_carts_1.0

Time after which a shopping cart is considered abandoned (min. 5 minutes):

Number of minutes until a shopping cart is considered abandoned. Recommended setting: 120
The time should be divisible by 5 and the CRON controller that controls the check should not run more frequently.

Send shopping cart abandonment emails to contacts without permission:

Should shopping cart abandonments also be transmitted to Maileon for contacts without newsletter consent? If yes, this option must be activated.

Custom Contact Fields:

For custom forms, the names of the errors to be passed to Maileon can be defined in a semicolon-separated list. The spelling of the names of the fields and the custom fields in Maileon must be identical, including upper and lower case.

If a field is not found in the form data, it will be ignored. If the field does not exist in Maileon, the API will return an error, which will be logged.

Advanced configuration and initial service

If required, the menu item "Marketing" - "Maileon Manager" (Figure 7) can also be used to view current newsletter subscribers and synchronise all subscribers (also from before the module was installed) with Maileon. Furthermore, the manager shows the settings for the webhooks that have to be set up in Maileon and allows the transaction types to be created manually in Maileon. Otherwise, these would only be generated the first time they are used. However, if you want to have all or individual mailings generated before testing, such as an order confirmation mail, then it is advisable to create the transaction type in advance in order to gain access to its variables in the template.

Import all newsletter subscriber into Maileon

In the first step, the permission that the contacts are to receive when imported into Maileon must be selected. In contrast to the settings on the configuration page, a mass transfer assumes that a corresponding permission exists for each contact. No DOI mail is sent, but the contacts are entered directly into Maileon with the selected permission.

Clicking the "Send all" button (Figure 8) starts the process. Depending on the number of contacts, the process can take several minutes. Afterwards, the UI notifies about success or errors that have occurred.

Configuration information for the Maileon webhooks

The configuration parameters for the Maileon webhooks are displayed here, see Figure 10 and Figure 11.

Create and update transaction types

With this option, transaction types can be created in advance in order to use them in Maileon. If there have been changes to a transaction type in a plug-in update, for example in 1.4.13, new attributes can be added to the affected transaction types via the update button.

Product properties config

This section is only visible if “Product properties send in transactions” is enabled in the plugin settings!

Warning, these settings will be lost if you uninstall or reinstall the plugin. In these cases you will need to re-enter the settings!

For products where variations are available, the variation details will be included in the order per product transaction (shopware_ordered_products_2.0). As variations can have different properties, you need to set in this interface (Figure 10) which variation properties should appear in which transaction fields.

The drop-down box lists the available variant config groups (Figure 11). The per product transactions (shopware_ordered_products_2.0) contains 10 generic pre-created fields, to which we can assign the desired variant config group.

After configuring the above settings (in this example, the Generic String 3 transaction field is paired with the Color variant config group and the Generic String 4 transaction field is paired with the Size variant config group), the following transaction is created in Maileon for a variant product (Figure 12):

Transferred contact data

The plugin transfers a series of contact data to Maileon. These include, if available, e.g. first name, last name, but also the ID of the (sub-)shop from which the registration comes. This chapter contains a list of all transferred contact information.

Field name	Field type	Description

Field name	Field type	Description
FIRSTNAME	standard
LASTNAME	standard
SALUTATION	standard
ADDRESS	standard
ZIP	standard
CITY	standard
ORGANIZATION	standard
BIRTHDAY	standard
Shopware_NL	custom	Custom field with boolean value true (=registration came from Shopware)
Customergroup_key	custom	The ID of the Shopware customer group to which the contact belongs.
Customergroup_name	custom	The name of the Shopware customer group to which the contact belongs.
shopware_store_id	custom	The ID of the (sub-)shop from which a contact originates.
Shopware_url	custom	The URL from which a contact was created.
Shopware_hash	custom	The hash value used for identification in the DOI process.

Customised forms for registration

In addition to the usual login methods provided by Shopware, the plugin also supports customised login and logout pages. For this, it is important that the form is given a corresponding marker:

<input id="subscribeToNewsletter" name="subscribeToNewsletter" type="hidden" value="1">

If the value 1 is set here as "value", it is a registration form. If the value is -1, it is a deregistration form (the entered e-mail address would be deregistered).

Currently, only the following form values are transmitted (name of the inputs):

email
firstname
lastname
salutation

Furthermore, custom fields can be inserted into the form and transmitted to Maileon. However, this requires an entry in the configuration (last point, Figure 6).

Finally, a forwarding in case of success can be set up by inserting a hidden form field with the name "redirect":

<input type="hidden" name="redirect" value="http://landingpageurl.de">

Settings to be made in Maileon

To synchronise DOI confirmations and unsubscribers with Shopware, a webhook can be entered in Maileon for DOI confirmations and unsubscribers. Maileon webhooks are configured in Maileon under "Settings" "Webhooks". If the menu item is not available, a sales partner or service employee can activate it.

DOI confirmations

A new webhook must now be added for the "DOI login confirmation" event. For this, the URL and the webhook ID from the "Maileon Manager" (Figure 13) must be used.

The webhook expects four parameters:

email (required): The email address of the contact must be entered here.
code (required): For security reasons, the secret code is inserted here. To prevent this code from being read, it is recommended to use an SSL-encrypted connection.
reg_date (required if hash param is not set and DOI process is enabled in Shopware basic settings)
hash (not required): Since version 1.4.4 it is possible to add a parameter 'hash'. If the parameter is not present, then the plugin works as before, but if the parameter is set, then DOI confirmers are only registered in Shopware if the hash is correct. This function is useful if several physically separated shops are to be controlled from one Maileon account. In this case, a webhook is called on each shop but only the shop to which the contact really belongs will register it.

Unsubscribe

A new webhook must now be added for the "Unsubscriber" event. For this, the URL and the webhook ID from the "Maileon Manager" (point 5 in the installation chapter) must be used.

The webhook expects two parameters:

email: The email address of the contact must be entered here.
code: For security reasons, the secret code is inserted here. To prevent this code from being read, it is recommended to use an SSL-encrypted connection.

Using the plugin from within other plugins

Plugins can use the Maileon plugin to register contacts. This can be the case if a separate login logic has been implemented. For this purpose, the Maileon plugin offers the service "maileon_plugin.maileon_subscribe" as of version 1.4.11. This can be registered in the own plugin and then used as follows. This can be registered in your own plugin and then used as follows:

services.xml:

<services>
	<service id="swag_test_plugin.subscriber.register_customer" class="SwagTestPlugin\Subscriber\RegisterCustomer">
		<argument type="service" id="maileon_plugin.maileon_subscribe"/>
		<tag name="shopware.event_subscriber"/>
	</service>
</services>

Implementing class (registered above as "SwagTest\Subscriber\RegisterCustomer")

namespace SwagTestPlugin\Subscriber;

use Enlight\Event\SubscriberInterface;
use xqueueMaileonShopware5\Components\MaileonSubscribe;


class RegisterCustomer implements SubscriberInterface
{
    /**
     * @var $taxCalculator TaxCalculator
     */
    private $maileonSubscribe;

    public function __construct(MaileonSubscribe $maileonSubscribe)
    {
        $this->maileonSubscribe = $maileonSubscribe;
    }

    /**
     * {@inheritdoc}
     */
    public static function getSubscribedEvents()
    {
        return [
            'Shopware_Controllers_Frontend_Register::saveRegisterAction::after' => 'afterSaveRegisterAction',
        ];
    }

    public function afterSaveRegisterAction(\Enlight_Event_EventArgs $args)
    {
        $this->maileonSubscribe->subscribeMaileon(
            'test00005@xqueue.com,
            array(
                'firstname' => 'Test',
                'lastname' => 'Contact',
                'salutation' => 'mr.',
                'street' => 'Test str. 5.',
                'zipcode' => '1122',
                'city' => 'TestCity',
                'company' => 'TestCompany',
                'birthday' => '1970-07-04',
                'customergroup_key' => '1',
                'customergroup_name' => 'test'
            )
        );
    }
}

Changelog

Version 1.4.17, 2023.11.15
- If the cart is abandoned, the process will not stop if the currency is not set for the cart.

Version 1.4.16, 2023.08.29
- Bugfix: If the "Automatically add buyers to newsletter" set to "All customers" or "Only registered" (registered customer) and the contact not exist at Maileon, the contact is not created.

Version 1.4.15, 2023.08.03
- Add product variant data to order confirmation and ordered product transactions.
- Add customer group data when contact created/updated before send a transaction.

Version 1.4.14, 2023.05.30
- Bugfix: Check article is not empty at order confirm.

Version 1.4.13, 2023.05.19
- Contact event update functionality added.
- Manufacturer number added to order contact events.
  - If the new attribute is to be used, the contact event must be updated manually.

Version 1.4.12, 2023.01.18
- Bugfix: If Captcha is activated when registering for a newsletter and is entered incorrectly, the contact is no longer registered with Maileon.

Version 1.4.11, 2022.05.31
- Added a service that allows other plugins to use the login and logout functions of the plugin.

Version 1.4.10, 2022.05.17
- Added transfer of customer data when a logged in customer registers for the newsletter in the order process.

Version 1.4.9, 2022.04.29
- Use of MediaServiceInterface instead of the class MediaService for better extensibility when analysing cancelled shopping carts and status changes of orders.

Version 1.4.8, 2022.04.11
- Customers can register for the newsletter when ordering
- Automatic registration of buyers is now only related to the corresponding option and no longer to whether order confirmation transmission has been activated or not.

Version 1.4.7, 2022.02.25
- Product SKUs added as comma separated list to order confirmation transactions.
- The previous extended order information (information about products, there was one transaction type per customer) was reduced to one transaction type.
- Product URL was added to the shopping cart abandonment transactions.

Version 1.4.6, 2022.02.03
- Bugfix: Processing of permissions "NONE" and "OTHER" when importing all contacts from Shopware to Maileon.
- Option to overwrite permissions when importing all contacts from Shopware to Maileon.

Version 1.4.5, 2021.12.06
- Contacts can be added directly to the distribution list during order confirmation. It is possible to add a separate permission for all customers or only for registered customers.

Version 1.4.4, 2021.11.17
- Added optional parameter 'hash' to DOI confirmation webhook to identify if a reported contact belongs to this very Shopware instance.
- Added customfields Shopware_url and Shopware_hash.

Version 1.4.3, 2021.10.28
- Bugfix: As of Shopware 5.7.0 administrators were logged out, who called the Maileon Manager in the Marketing menu in the backend.

Version 1.4.2, 2021.10.19
- When subscribing to the newsletter, if the subscriber already exists at Maileon and has a valid authorisation, the OptIn is entered directly in Shopware.

Version 1.4.1, 2021.09.28
- Updating and translating of configuration.
- Added API test button.

Version 1.4.0, 2021.09.21
- Updated code to be compatible with Shopware plugin store. Installing 1.4.0 requires complete uninstallation of previous versions.

Version 1.3.9, 2021.09.17
- Changed to composer version of Maileon PHP API client.
- Bugfix: Handle if article model not found at order transactions.
- Bugfix: DOI confirm webhook processes data now correctly, if captcha is enabled.

Version 1.3.8, 2021.09.03
- Updated Maileon PHP API client library.
- Add functionality to add separate Maileon permission for buyers.

Version 1.3.7, 2021.02.08
- Fix redirect when newsletter subscribe form uses captcha.

Version 1.3.6, 2021.06.23
- Updated deprecated log methods.

Version 1.3.5, 2021.06.21
- Added Birthday to standard contact field sync.
- Added order confirmation transaction data: order.brands and order.categories will now be filled.
- Fixed problem when contacts were not registered with Maileon when an invalid custom field mapping was configured.

Version 1.3.4, 2021.03.17
- Add DOI confirmation date to DOI confirmation webhook.

Version 1.3.3, 2021.03.17
- Fixed bug with abandoned carts and multiple subshops.
- Newsletter subscribe validation update.

Version 1.3.2, 2021.02.24
- Order transaction type attributes updates.
- Split DOI and transaction mails switch at config.
- Add enable/disable functionality to send subscribers to Maileon.

Version 1.3.1, 2021.02.12
- Old transaction types are available in addition (backwards compatibility).
- Fixed “Get Shopware version” bug that prevented e.g. password reminder mails from being sent in some Shopware versions.
- Fixed bug with subshop configs bug.

Version 1.3.0, 2021.02.08
- Change permission logic (added explicit initial permission and DOI, DOI+ process).
- Add extended order transaction types (v1.0).
  BE AWARE: This update creates new transaction types. Mails bound to the old type WILL NOT be sent anymore. Make sure to first create the types, e.g. from a staging system, create the mails and then install this update on your live system.
- Add functionality to create all transaction types at Maileon by clicking one button in the Shopware settings.

Version 1.2.8, 2021.01.27
- Fixed problem with abandoned carts not being sent to contacts without permission.

Version 1.2.7, 2021.01.12
- Fixed popup not showing up when changing order states from open to “in process”.

Version 1.2.6, 2020.12.21
- Fixed problem with invalid password reset links in versions below Shopware 5.4.5.

Version 1.2.5, 2020.11.03
- Custom fields submit at Newsletter subscribe form and redirect after submit.

Version 1.2.4, 2020.08.11
- Added custom field shopware_store_id for subscribers.
- Added abandoned carts transactions.
- Updated plugin backend structure.

Version 1.2.3, 2019.05.15
- Subscriber sync add customergroup key and name.

Version 1.2.2, 2019.05.13
- Transactions float format change.

Version 1.2.1, 2019.03.05
- Order and payment status transactions extended.

Version 1.2.0, 2019.03.01
- Added order and payment status transactions to Maileon.

Version 1.1.0, 2018.05.03
- Plugin handle for subshops and language shops.

Version 1.0.10, 2018.03.08
- Bugfix “empty unsubscribe”.

Version 1.0.9, 2018.02.21
- Config extend set Maileon API timeout value.

Version 1.0.8, 2018.02.07
- Config extend disable Shopware mails.
- Doi confirmation bugfix.

Version 1.0.7, 2017.12.14
- Plugin view js loader disable.

Version 1.0.6, 2017.11.27
- Bugfix at Maileon api client (trim doikey).

Version 1.0.5, 2017.08.09
- Required min version change.

Version 1.0.4
- Bugfix Shopware mails.

Version 1.0.0
- Subscribers sync.
- Alle Subscriber sync.