Mautic: Develop Your Custom Marketing Integration Plugin

When it comes to Open Source software/technology, it profoundly relies on its community. So being a part of this community, we welcome you to this blog series to kick start integrating other marketing tools with Mautic.

In this first post, we uncover the use of IntegrationBundle to extend the Mautic. After that we will register a simple plugin. To begin with, let's get to knot the Mautic and IntegrationBundle.

"Cutting edge marketing automation empowered by Open Source technology. This is the future; Mautic is leading the way," David Hurley, Founder of Mautic.

The Mautic

The Mautic is the only OSS marketing tool available in the digital marketing space. It helps organizations gather essential contact information, create campaigns and produce the report on results.

Mautic helps businesses to integrate other marketing tools to have a one-stop lead generator with multiple other benefits. 

The plugins

As per the wiki, "In computing, a plugin (or plugin, add-in, addin, addon, or addon) is a software component that adds a specific feature to an existing computer program. When a program supports plugins, it enables customization."

The Mautic comes with build-in plugins to integrate Hubspot, SalesForce, Instagram, LinkedIn, Gmail, and others. These plugins synchronize the data to and or from Mautic.

The IntegrationBundle

In Open Source, technology comes with essential yet generalized solutions. Therefore, we may have to plug it with a custom plugin to support our business needs. This plug-ing has a process per tech-stack. 

When it comes to Mautic (3.x), the IntegrationBundle defines the rulesets to add custom plugins to support integrations. The IntegrationBundle enables developers to use the service tags, a way to tell Mautic that your service should be registered in some special way. These services are listed in later sections.

The following points uncover the ways of preparing the development of any custom plugin:

  • Telling Mautic about your custom plugin
  • Type of authentication to pull/push data to Integration's API
  • Fields to map
  • The direction of Sync (pull, push and/or both)
  • The point award system
  • The segment and needed filters

In the first part of this series, let's learn how to register a custom plugin with Mautic.

Here I am assuming you have ready-to-use Mautic plugin development instance.

Step One

We should tell Mautic the name, description, and authors of the new custom integration plugin.  

  • Let's create a directory, HelloWorldBundle, in the plugins directory. This directory will host all the files that cater to the custom logic related to the plugin.
  • Now it's time to create a HelloWorldBundle.php file in the newly-created directory. Add the following code listing: 

The class HelloWorldBundle extends the AbstractPluginBundle, which helps register the plugin with Symfony. Every plugin should have <PluginName>Bundle.php file.

  • It's time to have the plugin configuration, the Mautic uses the Config/config.php file to read these plugin configurations. The config.php file returns the simple associative array with self-explanatory keys. 

Let’s create a config.php with the following code snippet:

The above snippet is the general section of a config.php, and it defines what should be listed. 

Step Two

All integrations, whether it uses the basic, config, auth, or sync interfaces, must have a class that registers itself with Mautic. This step will register the custom plugin as integration.

Now, we will create classes that will tag with the service tags of the IntegrationBundle. This means we will be creating service classes to let Mautic know that this Integration is ready to be listed.

Let's create the following class in the Integration sub-directory:

  • HelloWorldIntegration.php
  • ConfigSupport.php


The class HelloWorldIntegration enables a developer to provide a unique name, icon, and the display name for the plugin. The class should extend \Mautic\IntegrationsBundle\IntegrationBasicIntegration and should implement \Mautic\IntegrationsBundle\Integration\Interfaces\BasicInterface. This helps define the getName(), getDisplayName() and getIcon()methods. And it uses the ConfigurationTrait to store the configuration related changes.

To have the plugin's icon, please add the image of 125x125 resolution to the Asset/img directory. The filename should be the plugin's short name. In our case, it is helloworld.png. The directory Assets hold the style-sheets, javascript, and image files. 

The following code listing is for the class:


The class ConfigSupport tells the IntegrationsBundle that this integration has configuration options. The class must implement Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormInterface to have a configuration modal form for the plugin and Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormAuthInterface to have Enable/Auth tab for the plugin. These interfaces provide the configuration options for authenticating with the 3rd party service.

In this class, the method getAuthConfigFormName() returns the name of the configuration form. In our case, it is the class name ConfigAuthType::class, which returns the configuration form. The Class has the following definition: 

Step Three

Here comes the critical step, let the Mautic know these classes are the services and tag them with designated service tags.

The following is the part of the config.php file:

The new additions to the config.php are the services. 

Services are PHP objects stored in the service container and used throughout Mautic. 

In the services section of config.php, we have used the integrations key to represent classes that enable the integrations with the help of service tags.

In our case, we tagged our HelloWorldIntegration class with 'mautic.integration' and 'mautic.basic_integration'. These tags help Mautic to know via IntegrationBundles that this plugin is the integration plugin.

And the ConfigSupport class with 'mautic.config_integration'. This tag enables the custom plugin to integrate with the Configuration UI.

Other than integration services, there are a few different types of services listed below in a nutshell:

  • commands: This lets you define the console command classes.
  • events: This defines event subscriber classes used to listen to events dispatched throughout Mautic and auto-tagged with 'kernel.event_subscriber.'
  • forms: This defines custom form types and auto-tagged with 'form.type.'
  • helpers: This defines custom template helpers. These services are auto-tagged with 'templating.helper.'
  • others: This defines all other custom services.
  • sync: This defines the sync related services.

Step Four

Now that we have all things wired up. The plugin directory will have the following structure:

Step Five

It's time to load the plugin. Follow the steps to load the plugin:

  1. Browse the installed Mautic, e.g., https://localhost/mautic
  2. Login with admin credentials
  3. Click on the top right corner gear icon
    Dashboard of Mautic
  4. Click on Plugins menu link from the expanded block
    Dashboard of Mautic
  5. It will navigate to the list of available plugins
    Mautic plugin listing
  6. Click on the top right button Install/Upgrade Plugins to install our plugin. It will refresh the plugin list, adding HelloWorld plugin to the list. 
    Icon of HelloWorld plugin highlighted in the listing
  7. To enable the plugin, click on the icon, which pops open the configuration modal. Select 'Yes' and then click on the Save & Close button. 
    HelloWorld config modal popup
  8. Congrats, we have successfully installed and enabled the plugin!

Some Tips and Tricks

  • Please clear the cache every time you make changes to config.php
  • The cache folder path is <mautic-root>/var/cache/prod
  • The logs are located in <mautic-root>/var/logs


At last, we have successfully registered and installed a custom HelloWorld Mautic plugin. Thanks, IntegrationBundle, to help us integrate with Mautic. 

It is just the beginning of the plugin to manipulate data, so stay tuned to this space.