Sign in Subscribe

Mautic 5: Key Gotchas and How to Navigate Them

Long awaited Mautic 5 is finally here šŸ„³ Ready to install?

Mautic 5 comes with some significant changes. Because of at least one you might want to wait for a bit before you updateā€”as you could, for example, accidentally destroy your sender reputation.

With great changes come great challengesā€”or something like that...

Here's a list of things you need to be aware of before updating.

  • How the switch to Symfony mailer transports slows your emails sending down and might even accidentally hurt your sender reputation.
  • The need to have and run NPM (Node.js package manager).
  • Removed Mautic core plugins.
  • Changes to transactional email sending.
  • Removing mautic:emails:send.
  • The final death of the froala editor.
  • Special character issues with mailer_dsn.
  • List of known bugs in Mautic 5.

Switch to Mailer Transports

Mautic's shift towards using Symfony email transports and third-party plugins for email delivery means the built-in email transports are gone.

Personally, I find that problematic. From a user perspective this means a temporary regression. This is for two reasons:

  1. Symfony's transports donā€™t support batch sending, even via API. As a result, you can only send one email per request, as opposed to a thousand emails per request as was the case with some Mautic 4 transports.
  2. Symfony's transports donā€™t support transport callback handling. This was used for bounce management. The result: you lose the built-in bounce management.

(You can set it up another way, but you need to know that!)

I guess, this decision will turn out to be a very good step in the future. That is, because Mautic devs do not need to care about the mailer transports anymore.

They can focus more on the core.

But currently, post-installation, SMTP remains the sole transport supported out-of-the-box.

What this means for you:

    1. You'll need to manually install your preferred mailer transport plugin.
    2. You will (at least temporarily) lose Mautic's bounce management functionality if you do nothing.

Especially the second point can hurt your sender's reputation if you are not aware of this. Without bounce management you might be considered a spammer at some point.

3rd party plugins are meant to bring back the bounce management. There are two plugins already ready for productive use:

How to Install Mailer Transports

  • Look for Symfony's mailer transport plugins that support your email service provider.
  • They are listed in the Sending Emails with Mailer in Symfony Docs.
  • Install these via composer.
  • Configuring the Mailer DSN:
    • DSN is short for Data Source Name.
    • This essentially tells Mautic how to connect to your email service, including the type of service, credentials, and other necessary parameters.
    • You can set it up in the configuration dashboard.
    • The documentation page above tells you how to do that.

Configure Bounce Management

If you relied on Mautic 4's built-in callbacks that processed bounce management, you'll need to manually configure a Monitored inbox. Check the docs:

Emails ā€” Mautic Documentation 0.1 documentation

Without it, email addresses that bounce an email won't get flagged DNC.

NPM as an Installation Requirement

The inclusion of NPM in the setup process marks a significant technical shift for

Mautic 5 means to enhance the installation and build process and asset management.

This led to the inclusion of NPM in the setup and update process.

I see main problems:

  1. The NPM build process is resource hungry.
  2. Some shared servers don't come with NPM.

If you encounter one of these two problems, try building the JS assets locally and sync them to your production environment.

  • My Current Workaround: Sync your Mautic instance to your local machine, run the NPM build locally, and then sync it back. Here's how you can do it on a Linux system:
cd /tmp
mkdir mtc
cd mtc
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' user@domain.com:/var/www/mautic/ .
npm install
npm ci --prefer-offline --no-audit
npx patch-package
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' . user@domain.com:/var/www/mautic

Tip: Make sure NPM is installed on your local machine for this workaround šŸ˜‰.

Special Characters in mailer_dsn

Mautic 5 doesn't play well with special characters in the mailer_dsn, particularly in passwords.

The reason is unknown to me.

If you encounter issues, try changing the password. Creating and using passwords without special characters is the workaround for now.

For more, see the relevant GitHub issue and this issue.

mautic:emails:send Removed

Mautic 5 uses the Symfony Messenger. This comes with a transition from mautic:emails:send to mautic:messages:send.

You need to adjust crons and other scripts.

Legacy Froala Builder Disabled

For those still using the legacy email or page builder, the Froala editor is disabled by default in Mautic 5.

Reactivating it is possible but requires manual intervention. Refer to PR #12416 for details.

Transactional Emails Override DNC

A significant update is the handling of transactional emails:

Mautic sends transactional emails now regardless of a contact's 'do not contact' status.

This makes sure that crucial (account-related) communications reach your contacts.

If you (for some reason) marked marketing emails as transactional (e.g., to send them multiple times or in different campaigns) you need to change that.

Also: Transactional emails don't come with an unsubscribe header anymore.

Removed Mautic Core Plugins

In Mautic 5 several core plugins were removed. This includes the

While these are no longer part of the core, third-party solutions are available and linked above.

List of Known Bugs

Here can you see the list of known bugs on GitHub.

That's a wrap. Hope this helps you make an informed decision whether to update right away or wait for a bit.

Happy marketing!

Comments ()