Introduction

Welcome to the user documentation for the Maileon Integration Extension for Shopware 6. This guide provides detailed instructions on installing, configuring, and using the plugin to synchronize customer data and automate marketing workflows with Maileon.

What is the Maileon Integration Extension?

The Maileon Integration Extension enhances your Shopware 6 store by seamlessly synchronizing subscriber data and sending key e-commerce events to Maileon. With this plugin, you can leverage Maileon’s powerful email marketing and automation capabilities to engage customers effectively.

Key Features

• Subscriber Synchronization – Automatically sync subscribers and unsubscribers between Shopware 6 and Maileon.

• Order Event Tracking – Send order confirmations and status updates to Maileon as contact events.

• Abandoned Cart Recovery – Detect abandoned carts and send the data to Maileon for targeted follow-up campaigns.

Requirements

• A valid Maileon account with API access

• API credentials (API key) for integration

• Shopware 6 store

Who Should Use This Extension?

This plugin is designed for Shopware store owners, marketers, and e-commerce managers who want to enhance their email marketing and automation strategies by leveraging Maileon’s advanced features. It helps businesses improve customer engagement, recover lost sales, and streamline communication.

Open

Figure 1: Example instance of Shopware

Installation

Check requirements

The Maileon Integration Extension is continuously developed and tested with the latest Shopware versions. However, major Shopware updates may introduce changes that are incompatible with older plugin versions. The table below summarizes the compatibility between the plugin and Shopware versions:

Install the Extension

You can install the plugin directly from the Shopware Store or via your Shopware administration panel.

Option 1: Install via the Shopware Store

1. Visit the https://store.shopware.com/en/xqueu37905376689f/xqueue-maileon-newslettermanagement.html .

2. Download the plugin.

Option 2: Install via Shopware Administration

1. Navigate to Extensions → My Extensions → Shopware Account.

2. Use the search bar to find Maileon Integration Plugin.

3. Click the three-dot menu (⋮) next to the plugin entry.

4. Select Install and wait for the process to complete.

5. Once installed, activate the plugin using the corresponding toggle button.

🎉 The plugin is now installed and ready for configuration! Proceed to the next section for setup instructions.

Open

Figure 2: Installation of the module

Open

Figure 3: Installation of module 2

Open

Figure 4: Installation and activation

Configuration

The module can now be configured by clicking on the three dots and then the "Configuration" button - button can be configured.

The plugin settings can be configured for all Sales channels or separately for each Sales channel. From the Sales channel drop-down menu, you can choose which Sales channel settings are displayed.

Open

Figure 5: General plugin settings

General configuration

Figure 5 shows the general settings of the configuration page where the API key and a target permission must first be specified for all sales channels or each sales channel individually. The API key can be created and viewed in the Maileon account under "Settings"→"API Keys". The permission controls whether the contact is entered directly with permission (e.g. SOI) or whether a DOI/DOI+ mail should be delivered.

Maileon API key

The API Key can be created and viewed in the Maileon account under "Settings" → "API Keys" and ensures the connection to the account. The connection can be tested via the "Test" button. If the API key is checked successfully, the message "Connection was tested successfully" is displayed. If the test is not successful the API key should be checked. Common errors:

1. Validity period exceeded

2. Key was deactivated in Maileon

3. Characters were truncated at the beginning or end

Maileon permission

• None: No permission. The contact will not receive newsletters.

• 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 newsletters, 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 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 for single user tracking. 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. newsletter performance is missing.

⚠️ Available since version 1.3.10 or 1.5.4

• Other: If no permission can be demonstrated, the method “Other” can be chosen. However, this is explicitly not recommended. Permission must always be demonstrable.

Maileon sends double opt-in (DOI) emails

Here you can specify whether the DOI mails are sent from Maileon or not. Recommended setting: yes.

IMPORTANT: The item does NOT suppress the DOI mails from Shopware. The DOI mail dispatch from Shopware itself can be disabled under "Settings → Flow Builder" via the newsletter.register entry.

To enable the double opt-in process, the Permission setting must be set to a value lower than Double Opt-in. Specifically, the Permission value must be None, Single Opt-in, or Confirmed Opt-in. If the Permission setting is configured as Double Opt-in or Double Opt-in Plus, the double opt-in process will not be initiated.

Double opt-in (DOI) key

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

Send contact event when a new contact is created at Maileon

⚠️ Available since version 1.3.10 or 1.4.9 or 1.5.2

The plugin can automatically send a contact event to Maileon whenever a new contact is created. The contact event name: shopware_contact_created_1.0

This feature allows you to trigger marketing automation workflows in Maileon immediately after a contact is added.

Send language code with double opt-in (DOI) key

If this option is enabled, the language code used by the subscriber will be appended to the end of the DOI key specified above, so that a language-dependent DOI mail can be sent from Maileon. Pattern: somedoikey_en-GB or somedoikey_de-DE
IMPORTANT: In Maileon, all DOI mailing completed with the code of the language used in Shopware must be created and activated. If the DOI mailing does not exist with the DOI key added to the language code, it will be resent by the plugin but without the DOI key, so the default DOI mail will be sent.

Open

Language codes in a Sales Channel

Set different API keys depending on language

For those webshops that use a Saleschannel with multiple languages and would like the data to be sent to different Maileon accounts for each language. More info: User documentation

Webhook Token

A randomly generated secret string used to identify the calls to the webhooks from Maileon. There is one webhook for DOI confirmations and one for unsubscribes so that these changes can be applied to Shopware immediately. Further setup of the webhooks is shown in chapter "Settings to be made in Maileon".

When registering a registered customer

When a store customer registers in his customer profile via the check mark it can be selected whether he is created directly with the target permission or whether a DOI process should be started.
Important note: This configuration setting is not available from plugin version 1.3.0, because this functionality is available from Shopware 6.5.x in the Shopware Newsletter settings. More info:

User documentation

Behavior when user changes email

If a contact registered to the newsletter changes his email address in the store, then three scenarios are possible:

1. The email address of the store customer is logically detached from the newsletter registration. Nothing else happens and the newsletters are still sent to the (verified) old email address.

2. The email address of the contact in Maileon is updated and the permission is kept. Here the customer must clarify with his data protection officer whether the granted permission also applies to a new e-mail address. This could be the case, for example, if the store does not change the e-mail address until it has been verified that the registered customer is also authorized to do so.

3. The contact's email address in Maileon is updated and the permission is reset. This triggers a new DOI process.

Resend double opt-in (DOI) email if the subscriber has already subscribed

If you enable this option, the DOI mail will send again for subscribers who have already subscribed but not confirmed and want to subscribe again on the subscription form. The option "Send DOI from Maileon" must be enabled, otherwise this option does nothing.

Maileon API Timeout

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

Shopware customer custom fields to sync with Maileon

The plugin allows you to synchronize selected Shopware customer custom fields to Maileon as contact custom fields.

In the plugin configuration, you can select which Shopware customer custom fields should be transferred. Only the selected fields will be included in the synchronization.

During contact synchronization:

• If the newsletter recipient is linked to a Shopware customer, the configured customer custom fields will be added to the Maileon contact.

• If a selected custom field does not exist yet in Maileon, it will be created automatically.

• Existing Maileon custom fields are validated before synchronization to prevent type conflicts.

• Field values are normalized to match Maileon’s supported data types.

• Date fields are converted to the Y-m-d format.

• Numeric and boolean fields are converted to the appropriate Maileon type.

• Text values are automatically truncated to 255 characters (Maileon limit).

If a type mismatch is detected between Shopware and an existing Maileon custom field, the affected field will be skipped to ensure a stable synchronization process.

This feature ensures that important customer-specific information stored in Shopware can be safely and automatically transferred to Maileon for segmentation and marketing automation purposes.

Custom contact fields

If custom fields are submitted for the subscription form, they will be included in Maileon. If multiple fields, separate them with semicolons. For example:

customField1;customField2;customField3

If a field is not found in the form data, it will be ignored. If the field does not exist in Maileon, the plugin will create it.

More info about add custom fields to Shopware NL form: Custom fields to NL Form Plugin

Customer permissions

Open

Enable separate newsletter permission for customer users

If customers should be automatically added to the newsletter after a purchase, this can be activated here. Buyers will then be added to Maileon, unless they have explicitly unsubscribed before or already have a permission. The type of permission can be configured in the next point. Before activating, the company's data protection officer should be consulted, as there may be different views of the legal situation here.

Customers newsletter permission in Maileon

Here you can specify the permission that will be automatically assigned to buyers.

Open

Enable customer registration synchronization

⚠️ Available since version 1.5.12

⚠️ Important legal notice

Before enabling this feature, make sure that your Shopware registration process collects valid customer consent for marketing communication according to the applicable legal requirements in your country.

The plugin does not add or validate consent checkboxes automatically. The consent handling must already exist in the storefront registration form.

The plugin can automatically synchronize newly registered customers from Shopware to Maileon and optionally subscribe them as Shopware newsletter recipients.
This feature is useful for stores where customers explicitly agree to receive marketing communication during the registration process via a custom consent checkbox.

If enabled, every newly registered customer will automatically be created or updated as a contact in Maileon after a successful registration in Shopware.

Customer registration permission in Maileon

Defines which newsletter permission is assigned to the customer in Maileon during synchronization.

Contact events settings (general and order confirmations)

Open

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

Maileon API key for contact events

Contact events can be sent via another Maileon account to avoid permission issues. If the field is empty, the regular API key will be used.

Sending orders to Maileon as contact events

This is where order information is sent to Maileon. This does not prevent Shopware from sending order confirmation mails, it only transfers the data to Maileon which can be used for filtering contacts for example. If order confirmation emails are to be triggered from Maileon, appropriate trigger emails must be designed and activated. Then you can deactivate the order confirmation mails from Shopware, as described in chapter "Configure Shopware system mails".

Transaction types:

• shopware_order_confirmation_customer_1.0

• shopware_order_confirmation_guest_1.0

• shopware_ordered_products_2.0

Send a separate contact event for each ordered product

If sending orders to Maileon as contact events is enabled, and you activate this option, the system will send the order in one contact event, and additionally, one separate contact event per product containing the product details. This allows Maileon to filter contacts based on more detailed product information.

Send customer account confirmation to Maileon as a contact event

Mails related to account creation and management.

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

Transaction types:

• shopware_account_confirmation_1.0

• shopware_account_doi_registration_1.0

• shopware_guest_doi_order_1.0

Send password reset to Maileon as a contact event

This option allows sending mails with a password change link via Maileon.

Transaction type:

• shopware_password_reset_1.0

Send order, shipment and payment status to Maileon as a contact event

This option allows sending appropriate notification via Maileon in case of order status, payment status or single item status changes.

• shopware_order_status_changed_1.0

• shopware_order_delivery_status_changed_1.0

• shopware_order_transaction_status_changed_1.0

Send wishlist to Maileon as a contact event

⚠️ Available since version 1.3.10 or 1.4.6

When a logged-in customer adds a product to their wishlist, the plugin automatically sends the product data to Maileon as a transaction. This allows you to trigger targeted marketing automation workflows based on wishlist activity. Only registered users with a valid email address are tracked. The data sent includes basic product information and customer reference details.

Note:

Before using this feature, make sure the wishlist functionality is enabled in the Shopware administration under

Settings → Shop → Cart Settings → Wishlist.

You must activate the wishlist for each sales channel where this feature should be available.

Contact event name in Maileon: shopware_wishlist_added_1.0

Send the list of product attributes to a custom contact field

⚠️ Available since version 1.1.2

Transfer product properties as custom fields in Maileon (Figure 7).

Open

Figure 7: Adding product properties to custom fields

Here you can select the attributes that are to be transferred to Maileon when an order is placed. If a product has several values for an attribute, all values will be transferred. The values are separated by the separator "|". A "rolling approach" is used for the values, which means that the new attributes are always placed at the beginning of the contact field, and duplicates are removed. If the entry becomes longer than 255 characters, the oldest values at the end of the list would be removed (Figure 8).

The fields in Maileon are created with the prefix "shopware_".

Open

Figure 8: Product properties as custom fields in Maileon

Send product attributes in the order contact events

⚠️ Available since version 1.1.2

Transfer product properties as contact event fields for order contact events (Figure 9).

Open

Figure 9: Adding product properties to contact event data

Similar to the attribute values in contact fields, these values are also separated by the "|" separator.

For regular order confirmation transactions, the values are simply added as new attributes to the product information.

For single transactions for products, on the other hand, mapping must be performed by an additional step, since here the information is at the top information level and Maileon requires a fixed structure of the data here. Here, a mapping must be set under "Marketing"→ "Maileon Plugin". Up to 10 values can be transferred to Maileon (Figure 10 and result in Figure 11).

Open

Figure 10: Attribute assignment settings

Open

Figure 11: Result of the data in Maileon

Shopping Cart Abandonment

Open

Figure 12: Settings for shopping cart abandoners

If a customer fills a shopping cart and does not order it is possible to send a reminder. This requires regular checks for unordered shopping carts.

Compared to many other store systems, there is a special feature to note here: In Shopware, unfortunately, only the creation of a shopping cart is directly noted in the database, but not the last change. Therefore, the reminder refers to the creation time. So the waiting period should be long enough so that the customer has enough time to shop, for example 2-4h. Another peculiarity is that due to the missing date of change, it is not possible to remind again after a reminder and subsequent change. This is only possible when the customer has completely emptied the shopping cart or ordered or the shopping cart has been cleaned by Shopware at some point.

Send shopping cart abandonments to Maileon

Transactions for shopping cart abandoners are sent to Maileon if this option is active.

Transaction:
shopware_abandoned_carts_1.0

After how many minutes a shopping cart should be reminded

This setting specifies the time period in minutes after the shopping cart has been created after which it should be reminded if it has not been ordered.

Create contacts without permission

Depending on the view of the respective data protection officer, a business relationship exists after a purchase and a contact may also be sent a newsletter. If this is desired, this option should be disabled, otherwise the contact will be created without permission.

Testing shopping cart abandoners

To test shopping cart abandoners, make sure that Shopware's task scheduler and message consumer are running. For testing, you can also do this manually by starting the following two applications:

1. ./bin/console scheduled-task:run

2. ./bin/console -vv messenger:consume

The -vv option outputs all consumed tasks and is only used for an overview during testing. It is not necessary for live operation.

The transaction type shopware_abandoned_carts_1.0 is then created in Maileon. The version number refers to the default definition 1.0.

⚠️ Available since version 1.2.4

You can also run the abandoned cart from the command line for testing. You can using the following commands:

Mark abandoned carts

Use this command to search for abandoned carts in the carts table. If the command finds an abandoned basket it will save it in a separate table.

Send abandoned carts

Sends the details of the abandoned basket to Maileon.

Delete abandoned carts

Delete abandoned carts without references.

Event-based shopping cart abandonment handling

⚠️ Available since version 1.5.11

Open

The plugin now supports a new event-based shopping cart abandonment strategy in addition to the legacy database-based mode.

The new mode was designed to improve reliability and compatibility with modern Shopware installations, especially when Redis is used for cart storage.

In the legacy mode, abandoned shopping carts are detected directly from the Shopware cart database table. This approach has several technical limitations:

• Shopware only stores the cart creation date

• cart updates are not reliably tracked

• repeated reminders after cart changes are difficult

• Redis-based cart storage may not work reliably with the legacy detection method

The new event-based strategy solves these limitations by introducing a cart snapshot system.

Whenever a shopping cart changes, the plugin stores a snapshot of the cart state in a dedicated database table. These snapshots contain:

• cart token

• customer information

• sales channel

• cart value

• item count

• currency information

• cart payload

• last cart activity timestamp

The abandoned cart detection is then based on the latest cart activity instead of the cart creation date.

This provides several advantages:

• more reliable abandoned cart detection

• proper support for Redis-based cart storage

• improved cart reactivation handling

• duplicate prevention

• automatic cleanup handling

• improved monitoring capabilities

Abandoned cart handling strategy

⚠️ Available since version 1.5.11

The plugin now provides two strategies:

Database-based (legacy)

Uses the original Shopware cart database table directly. This mode is mainly kept for backward compatibility.

Event-based

Uses cart snapshots generated from cart change events. This mode is recommended for modern Shopware installations and Redis-based cart storage.

Cart reactivation handling

⚠️ Available since version 1.5.11

The event-based strategy supports cart reactivation scenarios.

Example:

1. A customer abandons a cart

2. The abandoned cart is processed

3. The customer returns and modifies the cart again

4. The cart can become abandoned again later

The plugin automatically updates the cart snapshot and prevents duplicate pending abandoned carts.

Automatic cleanup

⚠️ Available since version 1.5.11

The plugin now automatically cleans old processed cart snapshots and successfully processed event-based abandoned carts.

This cleanup helps reduce unnecessary database growth while keeping failed or pending abandoned carts available for troubleshooting purposes.

Administration overview

⚠️ Available since version 1.5.11

A new administration overview page for abandoned carts is now available.

The overview contains:

• cart token

• customer email

• sales channel

• abandoned cart source

• cart value

• item count

• send attempts

• send status

• comments

• creation and update timestamps