Oxid eShop

Introduction

This document provides instructions on installing, configuring, and using the Maileon OXID eShop module for OXID eShop. The module allows you to synchronise your subscribers with Maileon, send order details to Maileon or create an RSS feed of your products.

Key features

• Seamless initial synchronisation of subscribers with Maileon.

• Automated synchronisation of subscriber and unsubscriber statuses with Maileon.

• Transmission of order confirmation details to Maileon as a contact event.

• Sending abandoned cart details to Maileon as a contact event for targeted marketing campaigns.

• Generation of an RSS feed from your product catalog for enhanced content distribution.

Requirements

Installation

The module is using contact preferences in Maileon, so please check the contact preferences is turned on, at your Maileon account.

Open

Contact preferences at Maileon

The plugin can be installed from the command line. The installation steps:

Prepare

• Unzip the package and copy the content (xqueue) into your [SHOPROOTDIR]/source/modules/ directory

• Add the repository to composer.json.

  composer config repositories.xqueue/maileon-oxid-module \ --json '{"type":"path", "url":"./source/modules/xqueue/maileon-oxid-module", "options": {"symlink": true}}'

• Add the maileon-oxid-module to composer

  composer require xqueue/maileon-oxid-module:dev-main --no-update composer update --no-interaction

Install module

• Oxid eShop 6.x.x

  vendor/bin/oe-console oe:module:install-configuration source/modules/xqueue/maileon-oxid-module/

• Oxid eShop 7.x.x

  vendor/bin/oe-console oe:module:install source/modules/xqueue/maileon-oxid-module/ vendor/bin/oe-console oe:module:install-assets

Activate the module at admin

1. Log in to your OXID eShop Admin Panel.

2. Navigate to Extensions > Modules.

3. Find Maileon - E-Mail Marketing in the list.

4. Click Activate to enable the plugin.
   
   

Open

Activate the plugin

Activate at command line

Set cronjobs

After installing, you need to set up a cronjob and an optional cronjob if you want to use the abandoned cart functionality.

Plugin status cronjob (Run every day once)

Abandoned cart cronjob (optional) (Run every 5 minutes)

Uninstallation

The plugin can be installed from the command line. The installation steps:

• Deactivate the plugin at admin or at the command line

  vendor/bin/oe-console oe:module:deactivate xq_maileonoxidmodule

• Uninstall the module:
  Oxid eShop 6.x.x

  vendor/bin/oe-console oe:module:uninstall-configuration xq_maileonoxidmodule

  Oxid eShop 7.x.x

  vendor/bin/oe-console oe:module:uninstall xq_maileonoxidmodule

• Remove the package from composer

  composer remove xqueue/maileon-oxid-module --no-update composer update --no-interaction

Settings

After installation you can see the settings interface at the plugin Settings tab.

Subshops

With Oxid Enterprise Edition, sub shop management is also possible. In this case you can choose on the top left of the admin page which sub shop settings you want to see. This allows you to set different configuration settings per sub shop.

Open

Settings page

Open

Maileon Oxid Module - Settings page

Connection settings

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. Common errors:

• Validity period exceeded

• Key was deactivated in Maileon

• Characters were truncated at the beginning or end

Synchronisation of subscribers

Enabled

Here you can enable/disable the synchronisation of Oxid eShop subscribers/unsubscribers with Maileon.

Initial permission in Maileon

• None: No permission. The contact will not receive newsletters, only transaction emails (e.g. reservation confirmation mail).

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

• Confirmed Opt-in: With the confirmed opt-in, a confirmation e-mail is sent to the e-mail address after registering for the newsletter. However, this does not contain an additional confirmation link as with the double opt-in, the newsletter registration is valid immediately.

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

• Other: If no permission can be proven, the "Other procedure" method can be selected. However, this is expressly not recommended. Permission must always be proven.

If DOI process is enabled the permission must be lower then double Opt-in (DOI), so the valid permissions are None, Single Opt-in or Confirmed Opt-in!

DOI process enabled

If we enable the DOI process, then when the contact is created a confirmation email will be sent to the email address with a confirmation link, which if the contact clicks on will give them Double Opt-In Plus access to Maileon, regardless of what we have set in the above setting.

If at OXID admin (Core settings->Settings->Administration) the Double Opt-In settings is turned off and this option is turned off too, the contact will receive the permission set above instantly, without any confirmation.

If at OXID admin (Core settings->Settings->Administration) the Double Opt-In settings is turned on and this option is turned off, OXID will send the DOI confirmation mail.

If at OXID admin (Core settings->Settings->Administration) the Double Opt-In settings is turned on and this option is turned on, Maileon will send the DOI confirmation mail.

DOI mailing id

Here you can enter a DOI mailing ID, which determines which DOI mailing should be triggered as soon as a contact subscribes to the newsletter. The identifier can be set in Maileon or retrieved from the corresponding DOI mailing in the default settings. If the Maileon account has a default DOI mailing set in the settings, this field does not need to be filled in. Common mistake:

• The DOI process above will be enabled but the DOI key is not specified here and no default DOI mailing is set in the Maileon account.

Webhook token for DOI confirmation and unsubscription

We will use webhooks from Maileon to synchronise DOI confirmers and unsubscribers back. These webhooks need to be set up in Maileon, to set them up you need to enter this token. The token can be any text that does not contain spaces.

Initial synchronisation

Enabled

Initial synchronisation allows you to create subscribers in Maileon that were created before using the plugin. It is sufficient to run this once when you start using the plugin, after that the subscribers will be synchronized automatically. You can enable synchronisation here, see below for more information on running synchronisation.

Permission if imported contacts

You can set the permission for contacts to be created during import. This is a final permission, the DOI process will not run.

• None: No permission. The contact will not receive newsletters, only transaction emails (e.g. reservation confirmation mail).

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

• Confirmed Opt-in: With the confirmed opt-in, a confirmation e-mail is sent to the e-mail address after registering for the newsletter. However, this does not contain an additional confirmation link as with the double opt-in, the newsletter registration is valid immediately.

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

• Other: If no permission can be proven, the "Other procedure" method can be selected. However, this is expressly not recommended. Permission must always be proven.

Order confirmation transactions send to Maileon

Enabled

Here you can allow orders to be transferred to Maileon as contact events. See below for more details.

RSS feed

Enabled

Here you can enable the generation of RSS feed for your products. See below for more details.

Abandoned carts

Enabled

Here you can enable the abandoned cart functionality. (Cronjob needed)

After how many minutes a shopping cart should be reminded

here you can set after how many minutes the plugin will send abandoned cart transactions to Maileon. The minimum is 5 minutes and can be increased by 5 minute intervals.

DOI process

If you disable the DOI process in the plugin, you should also disable it in the shop, otherwise it may lead to different functionality and vice versa if you enable the DOI process in the plugin, you should also enable it in the shop.

Here you can set at the admin: Master Settings → Core Settings → Settings → Administration

Open

Enable/disable DOI for Newsletter at Oxid eShop admin

Initial subscribers synchronisation (CLI)

Overview

The Initial subscribers synchronization feature allows shop administrators to export newsletter subscribers from the OXID eShop database and synchronize them with Maileon. This ensures that all subscribed users receive marketing emails based on their preferences.

How it Works

• The synchronization runs via a command-line tool.

• It fetches all subscribed users from the OXID eShop database.

• The contacts are sent to Maileon using an API connection.

• The process runs in batches to prevent timeouts.

• If the synchronization stops, it can resume from the last processed contact.

How to Use

Running the Synchronization

To start exporting subscribers, run the following command:

This will begin synchronizing all newsletter subscribers.

Parameters

Resuming the Synchronization

If the process was interrupted (e.g., due to an API issue), you can resume from the last known position using an offset:

This command resumes the synchronization from the 5000th record, skipping previously processed contacts.

Progress

A progress bar will show the current status of the import, including how many orders have been processed.

Error Handling & Logging

• Invalid emails are skipped and logged.

• If the API encounters an issue, the process stops and logs the error.

• If the process stops due to an error, you can find in the logs how many subscribers have been successfully synchronized, and then continue from that point.

Language Assignment During Subscriber Import

When importing newsletter subscribers, the shop’s default language is assigned to each subscriber. This is necessary because neither the oxnewssubscribed table nor the oxuser table stores any language-related information.

At the time of subscription, OXID eShop determines the user’s language context from the session or browser cookies, which are not persisted in the database. Therefore, to maintain consistency and ensure that a language is always available for synchronization with Maileon, the system defaults to the shop’s configured default language.

Order history import to Maileon (CLI)

The order history import command allows you to export historical order data from your OXID eShop to Maileon via the command line. This includes customer, order, and product data. The data is transferred through the Maileon API.

Be careful! Orders will be imported by the process into this contact event type in Maileon: oxid_eshop_orders_2.0

If a trigger email is assigned to this contact event type in Maileon, an email will be sent to the customer for each order.
Please check that there is no trigger email associated with this transaction type before running this command!

Depending on the amount of data, this command can take a very long time to run, so we recommend that you run it in smaller chunks using the date and shop filters.

Also, it is important to run this command only after the initial subscribers synchronisation command, because this command will import all orders into Maileon and if it belongs to a customer who is not a subscriber it will create it in Maileon with NONE permission. It will not change the permission level of contacts that already exist in Maileon.

Command

Parameters

Examples

This will import all orders created in 2024 from shop ID 1.

This will import all orders created in 2024 from shop ID 1 and with offset (if the previous command timeouted)

This will import all orders created from 2025 with shop ID 1,2

Confirmation Prompt

Before starting the import, the command asks for confirmation to avoid accidental execution. You must type yes to proceed.

Progress

A progress bar will show the current status of the import, including how many orders have been processed.

At the beginning of the process, it prints out the total number of orders it has found that need to be imported. And at the end, it prints how many orders have been created. The process checks the customer's email address and if the email address is empty or not valid, the order will be skipped from the import.

Error handling

• If the Maileon API returns an error or an unexpected exception occurs, the process will stop.

• The log will contain details of the failure, including the offset and number of successfully exported orders.

• You can resume the export using the --offset parameter and the same shop_id, date filters.

Language Assignment During Order History Import

When importing order history data, the customer’s language is determined using the OXLANG field from the oxorder table. This field stores the language ID that was active at the time the order was placed.

The import process uses this language ID to resolve the corresponding language code via OXID’s language configuration. This ensures that the correct language is associated with each order and passed on to Maileon during synchronization.

If the OXLANG field is missing or null for any given order, the import falls back to the shop’s default language defined in the OXDEFLANGUAGE field of the oxshops table.

Order confirmation

Once enabled in the plugin settings, after each order, the order details will be transferred to Maileon as a contact event.

Contact event name: oxid_eshop_orders_2.0

The following data will be transferred:

Order items

Contact fields at Maileon

RSS feed

Once you have enabled RSS feed in the plugin settings, you can access the feed at the following url:

https://[MYSHOPURL]/index.php?cl=maileonrss

Available optional parameters

• lang => Id of the requested language ( 0 default, 1 en )

• articlenum => Article number of one single requested article

• limit => limit the list of all returned articles

Maileon webhooks

To synchronize DOI confirmers and unsubscribers we need Maileon webhooks. You can configure them in your Maileon account under Settings->Webhooks.

DOI confirm webhook

Open

HTTP post URL: https://[MYSHOPURL]/index.php?cl=maileondoi

URL parameters:

• external_id → Contact external id

• token → The token you set in the plugin settings

Unsubscribers webhook

Open

HTTP post URL: https://[MYSHOPURL]/index.php?cl=maileonunsubscribe

URL parameters:

• external_id → Contact external id

• token → The token you set in the plugin settings

Abandoned carts

Once enabled in the plugin settings and cronjob is configured, it will send abandoned cart transactions to Maileon after the configured time.

The abandoned cart feature only works globally, it cannot be set per subshop.

Contact event name: oxid_eshop_abandoned_carts_1.0

The following data will be transferred:

Cart items