Maileon for WordPress


Maileon for WordPress

This plugin helps you to set up forms for subscribing contacts with your mailing lists in Maileon. It is fully configurable and provides customizable templates for simple forms, a sidebar widget, and the possibility to build more complex forms e.g. with Contact Forms 7. Since version 2.6.0 it is possible to active AddressCheck for your form to prevent misspelled e-mail addresses.

Some features

  • Configuring your wordpress to connect with your Maileon account using the admin GUI
  • Use shortcodes to include a form whereever you want, different templates for different forms are possible
  • Multilingual support
  • AddressCheck support



Installing Requirements

Make sure cURL, SPL and SimpleXML for PHP are installed and enabled and that you are using PHP 5.6.x or higher.

Installing the plugin

  1. In your WordPress admin panel, go to Plugins > New Plugin, search for Maileon for WordPress and click "Install now"
  2. Alternatively, download the plugin and upload the contents of '' to your plugins directory, which usually is '/wp-content/plugins/'.
  3. Activate the plugin
  4. Set your API key under Settings -> Maileon.

Configuring Sign-Up Form(s)

The Standard Settings

You can add a standard form using the shortcode [maileon-contact].
The standard form provides input fields for the email address, first name and last name. Aditionally you can add a set of standard-/custom-fields with a predefined values, e.g. if you want to submit the german locale for every contact (fixed), you have to provide a JSON object with key-value pairs, where the key is the field name.
For standard fields use the attribute name "standard", for custom fields "custom". The keys for standardfields can be found here: Be careful to use correct capitalization, also for your custom fields. They must match exactly to the variable names you provided in Maileon.
Example: [maileon-contact standard="{'LOCALE':'de_DE'}" doimailing="myDoiKey"]

Please note that by default already existing contacts are not updated to avoid customers overriding information. If you think that updates should be allowed, please pass parameter sync_mode=1.
Example: [maileon-contact sync_mode=1]

Custom Forms

If you wish to add a custom form to use more fields in your form or use a different styling, just add your template to „\wp-content\uploads\xqueue-maileon\views“ (you might need to create that folder first). A basic template as described above can be found in file ‚maileon-contact-form.php‘, a version extended by gender selection is shipped with the plugin as example in ‚\wp-content\plugins\xqueue-maileon\views\maileon-contact-form-custom-sample.php‘. You can take a copy of those files and edit it according to your wishes. Make sure not to edit the original files or add files in the plugin folder as they will be overridden by updates.
To extend the standard form, just add new input fields according to the following scheme for the name of the field:

  • Standard fields have to start with "standard_" followed by the standard field name (see previous link). E.g. for the last name use "standard_LASTNAME".
  • Custom fields have to start with "custom_" followed by the custom field name (capitalization!). E.g. for the field "myCustomField" use "custom_myCustomField".
    You can then use the attribute ‚template‘ to select the file: [maileon-contact template=“maileon-contact-form-custom-sample.php“]

Configuring Sidebar Widget(s)

The sidebar widget can be added and customized like any other widget. It provides a single registration form. The title and submit button text can be changed in the widget settings and it uses the confirmation messages from the general plugin settings.

Integration With Other Form Plugins

The form can also be connected with other form plugins, here an example for Contact Forms 7.
The basic approach is to add the following hook to your WordPress by using a plugin like Code Snippets (

// ------------------------------ CF7 ------------------------------
// Prevent CF7 from sending mails
add_action( 'wpcf7_before_send_mail', 'xq_wpcf7_before_send_mail' );

function xq_wpcf7_before_send_mail( $wpcf7_data ) {
    // Since version 4.0 the author changed $skip_mail to be private, use hook instead
    //$wpcf7_data->skip_mail = true;

    $submission = WPCF7_Submission::get_instance();
    $formData= $submission->get_posted_data();

    // If only a form with a certain ID should be submitted, provide the id here
    // This can be extended to use an array of IDs or even check if a hidden field is available in the posted data...
    if (in_array($wpcf7_data->id(), array(16, 31))) {
        $result = XQ_Maileon::register_contact(null, $formData);

        // If there is an error set a message and add the error handler
        if (!$result['response']->isSuccess()) {
            global $message;
            $message = "Es ist ein Fehler aufgetreten: " . $result['response']->getBodyData();
            add_filter( 'wpcf7_ajax_json_echo', 'xq_wpcf7_ajax_json_echo', 10, 2 );
    return $wpcf7_data;

// Method to update the status message
function xq_wpcf7_ajax_json_echo($response, $result) {
    global $message;
    $response['mailSent'] = false;
    $response['status'] = 'mail_failed';
    $response['message'] = $message;
    return $response;

// New method to skip mails from CF7 itself
function xq_wpcf7_skip_mail($f){
    $submission = WPCF7_Submission::get_instance();
    return true;
// ------------------------------ End CF7 ------------------------------

This piece of code catches the submission of the form and checks if the ID of the form matches one of the provided elements, here 16 or 31. this check has been added to prevent all contact forms to submit data to Maileon, you can of course also remove this condition or check if a certain (hidden) post field is available. If the condition is fulfilled it registers the contact with Maileon. It also displays an error message in case of errors.
You can also pass configuration parameters in the form. The following are valid parameters and documented at:

  • [hidden doi "true"]
  • [hidden doiplus "true"]
  • [hidden doimailing ""]
  • [hidden permission "1"]
  • [hidden sync_mode "1"]

Adding AddressCheck (ADC)

You can help users preventing entering misspelled e-mail addresses by enabling AddressCheck in the plugin settings. ADC will check the mailbox of the e-mail address entered in your form in order to decide if it really exists or not. To enable AddressCheck, just provide your API user and API key and check „Use ADC“. You can also select an ADC check delay in seconds to prevent the plugin from checking the given address too often and an ID of the e-mail form field. The plugin will display ADC results by setting classes “, “, or “ to the e-mail form field and making an element with ID ‚adc_error_message‘ visible or invisible, depending if there is a problem or not. An example form with ADC can be found in template=’maileon-contact-form-adc-sample.php‘


How can I check error logs when something failed?

We do not show internal error information to frontend users. When you enable the WP debug mode (define('WP_DEBUG', true) and define('WP_DEBUG_LOG', true)) the plugin writes errors and warnings to the WP debug log, which you can usually find under /wp-content/debug.log.

When sending the form I only get a (more or less) blank page. Why?

Check your logs, most probably you do not have cURL for PHP installed. You should also see a warning in your administration panel.

When sending the form I always get an error even if my API-Key is correct. Why?

Check your logs, most probably trigger Maileon to send a DOI request but you have not specified a default DOI Mailing under "Settings -> Double-Opt-In". Please do so and retry.

When pasting a form from the documentation page I get strange errors when sending the form

If you get a warning like "Invalid argument supplied for foreach() path\xqueue-maileon\class\xq_maileon.php on line 306" it might be an issue with special chars generated by the webserver when displaying the manual. We noticed that some examples are displayed using different types of colons for ' or ". Please make sure to use only those two characters to mark strings etc. in your form descriptor, e.g. instead use [maileon-contact standard="{'LOCALE':'de_DE'}" doimailing="FF3OfzjS"] instead of [maileon-contact standard="{'LOCALE':'de_DE'}" doimailing="FF3OfzjS"]

When I copy your examples produce errors in my wordpress

Sometimes the plugin page for WordPress translates some signs like regular " or ' into special characters. You need to replace them by " and '.

Mitwirkende & Entwickler

„Maileon for WordPress“ ist Open-Source-Software. Folgende Menschen haben an diesem Plugin mitgewirkt:


2.6.2 – 20.02.2019

  • Updating CF7 instructions
  • Cleaning up code

2.6.1 – 11.12.2018

  • Fixed problem causing WordPress to be stuck for some time, when editing a template file and saving it

2.6.0 – 14.08.2018

  • Updated Maileon PHP api client to version 1.3.8
  • Added backend configuration for AddressCheck
  • Added frontend and backend code for including AddressCheck
  • Added example form for using AddressCheck

2.5.2 – 13.07.2018

  • Fixed bug when specifying a not-existing form template on a page causing the page to be non editable in backend
  • Added loading templates from wp-content/uploads/xqueue-maileon/views as fallback

2.5.0 – 11.07.2018

  • Added multilingual support under domain „xq_maileon“, it can be edited with WordPress „GetText“ as supported by simple language files or plugins like WPML
  • Removed CF7 sample code from plugin, removed instruction to add it there as it might be overridden when updating the plugin

2.4.2 – 04.05.2018

  • Fixed bug with not existing template tag

2.4.1 – 04.05.2018

  • Possibility to add data privacy acknowledgement checkbox and general newsletter subscription checkbox to form
  • Added setting for privacy description link

2.4.0 – 04.05.2018

Information: if you update, please make sure your form still works as expected as the templating system has changed.

  • Added option for selecting an own template file.
  • Changed templating to be able to use PHP code in own files to allow more flexibility

2.3.1 – 23.11.2017

  • Added debug attribut
  • Tested with WordPress 4.9

2.3.0 – 01.09.2017

  • Added options to display pages on OK or ERROR instead of messages on the same page
  • added page buffer to prevent „header not send“ errors when redirecting

2.2.6 – 31.08.2017

  • Fixed bug when submitting arrays in a form
  • Removed magic_quotes_gpc() (as deprecated) and strimpslashes

2.2.5 – 09.08.2017

  • Updates examples, tested responses for CF7

2.2.4 – 01.06.2017

  • Validated functionality for 4.8
  • Added proxy information from WP Constants WP_PROXY_HOST and WP_PROXY_PORT (thanks to @wdjac)

2.2.3 – 20.04.2017

  • Fixed displaying error details when the server failed to resolve the root CA of the certificate of
  • Added examples to description

2.2.2 – 22.11.2016

  • Fixed possible problem with some PHP versions not being able to disable DOI mailings

2.2.1 – 04.10.2016

  • Fixed encoding to UTF without BOM
  • Removed test

from default form template

2.2.0 – 04.10.2016

  • Added check if cURL for PHP is installed, otherwise an error will be displayed in the admin panel.

2.1.0 – 12.09.2016

  • Update version number to indicate realy old version was 1.0
  • Fixed problem with BOM in one file causing an error message when activating the plugin
  • Added more IDs to the standard form
  • Added config for enabling/disabling captcha for the standard form

1.0.0 – 31.08.2016

  • Initial version