There has never been such as powerful tool as Mautic for email marketing in a self-hosted environment, but it can be challenging for non-server admins to grasp its technical requirements. While the Mautic documentation & setup wizard tries to cover some of the bases how to correctly set up the platform, the Autoize team nonetheless sees many misconfigured instances of Mautic.
We are often called upon to troubleshoot Mautic instances set up by other freelancers and non-technical marketing firms. If you wonder why your Mautic instance can sometimes “hang” on a blank screen, or you notice entries in the error log (Settings > System Info > Log), most of these issues can be traced back to a mistake made during the Mautic installation or upgrade process.
That’s why we thought it would be helpful to compile a list of the most common Mautic configuration errors. Some of the other items on our list are more like encouraging a best practice, rather than correcting an error, so read on to find out what they are.
Deprecated Versions of PHP or Missing PHP Extensions
Mautic supports PHP 5.6 and up, but that doesn’t mean it’s a good idea to run anything below PHP 7.x for security & performance reasons. For Mautic versions prior to 2.15.0, up to PHP 7.1 is supported, with Mautic 2.15.0 onwards supporting PHP 7.2. To check which version of PHP is running on your Mautic server, go to Settings > System Info > PHP Info.
To upgrade PHP to a later version, we suggest using a trustworthy third-party repo such as IUS or Remi for CentOS and using yum-utils to disable the default, and enable the requisite version. We recommend using PHP-FPM instead of mod_php if possible, for greater scalability and performance.
For all the features of Mautic to function properly, it requires certain PHP functions which exist outside of the base PHP package as mods or extensions. Some of these functions are not checked for when the setup wizard launches, so run rpm -qa | grep php (on RHEL or CentOS) or dpkg -l | grep php (on Ubuntu or Debian) to ascertain which are installed.
php-zip php-xml php-imap php-mcrypt php-mysql php-mbstring php-curl php-amqplib php-mbstring php-bcmath php-intl php-process
Some other optional packages can accelerate the performance of the Mautic instance and are recommended, but not required prior to installing Mautic. Ideally, these user & system caches should be tuned for ideal performance, but they can work out of the box as well. For memcached, remember to enable its associated service by typing sudo systemctl enable memcached && sudo systemctl start memcached at a terminal.
php-opcache php-apcu php-memcached memcached memcached-devel
Misconfigured Values in php.ini
Mautic requires a memory_limit of 256M or more to prevent scripts from getting killed by being Out Of Memory. Users will see Mautic upgrades fail if the memory_limit is set to the default of 128M.
Furthermore, Assets larger than 2M cannot be uploaded if post_max_limit is set to the default of 8M and upload_max_limit is 2M. Because file uploads in PHP are buffered to disk (not memory), these values are not dependent on the memory_limit. Always set post_max_limit to equal or higher than upload_max_limit, otherwise problems will occur. We recommend between 64M to 128M for post_max_limit and upload_max_limit.
It may also be wise to increase the max_execution_time from the default of 30 (seconds) to 300 (5 minutes) especially if you have a larger contact database. Mautic is engineered to batch the sending of emails, import of CSV files, and execution of campaigns so that each batch falls below the max_execution_time but it’s safer to raise this value from the default.
Instance Not Secured with HTTPS
Never run a Mautic instance in production over plain HTTP — always use HTTPS. Major web browsers, such as Chrome, have marked any website without an SSL certificate (or with embedded HTTP resources) as “Not Secure” for a while now. Furthermore, transmitting your Mautic login credentials over the Internet without encryption is a very bad idea. It can allow a determined attacker to easily break into your Mautic instance and wreak havoc, anything from sending spam/phishing emails, stealing your marketing databases, or worse.
Luckily you can obtain a SSL certificate for your Mautic server from Let’s Encrypt for free. Setting it up requires some time investment, including updating your Apache VirtualHosts and configuring a cron job to automatically renew the certificate every three months. Like other commercial certificate authorities, Let’s Encrypt places a temporary file on your web server with a random string, and checks it to confirm control of your domain.
There are official plugins for the certbot ACME client designed to let you install a certificate on Apache or nginx without editing a configuration file, aptly named python-letsencrypt-apache or python-letsencrypt-nginx. These plugins are available as a software package from the epel-release repo for CentOS or ppa:certbot/certbot PPA on Ubuntu.
Incorrect File Permissions or Ownership
Incorrect file permissions can be the death knell of any PHP application, including Mautic. In general, files served publicly from your Apache DocumentRoot should always be owned by the Unix user Apache runs as. To find out which user Apache is running as, type ps -ef | grep apache at a terminal. On CentOS, Apache usually runs as apache and on Ubuntu, www-data.
For those unfamiliar with Unix file permissions, each time a file or folder is modified by a user (especially root), the ownership can pass to that Unix user. Since many people SSH into their VPS as the root user to download, extract, and install Mautic into their web directory, the Mautic files become owned by root.
The Mautic setup wizard will not even begin if the file or folder ownership is incorrect. To fix Mautic file permissions, use the following command where <apache_user> and <apache_group> are the name of the Unix user and group Apache is running as. Almost always, the user and group is the same; this setting is specified in httpd.conf. This assumes your Mautic directory is at /var/www/html, the most common location.
chown -R <apache_user>:<apache_group> /var/www/html
More often than not, 500 Internal Server Errors in Mautic are caused by incorrect file permissions. If a command from the Symfony PHP console is run, files are uploaded into the Mautic directory through scp, or cron jobs are executed as root, it can also cause Mautic files to take on the wrong ownership. The command above should be used to correct it.
To run commands against the Symfony PHP console located under your Mautic directory at app/console without breaking file permissions, use the sudo command as root. For example, to clear the Mautic cache, see the command below:
sudo -u <apache_user> php app/console cache:clear
Outdated Cron Jobs, with Delayed Segment Rebuild & Campaign Triggers
Mautic relies on a series of cron jobs to rebuild segments (when contacts meet a certain criteria specified by the filter), send scheduled emails, and trigger campaigns, among other tasks which are undertaken in the background. Over time, Mautic has added cron jobs to support new features, and deprecated others which are no longer applicable with each successive version.
For example, mautic:import was added to support CSV imports of large contact lists in the background, so the process would not be interrupted if the browser is closed mid-way during the process.
Not all Mautic users will require every cron job that is supported by Mautic. For example, if you never use the Social Monitoring or CRM Integration features, or are set to send emails immediately (most instances) instead of queueing them, don’t include the lines pertaining to those features.
Here is a common set of cron jobs that most Mautic users should have configured in /etc/crontab. Note that each cron job with the exception of mautic:iplookup:download is configured to run every 5 minutes, a good starting point for most instances. This means users who opt in through a form will wait no longer than 5 minutes to receive a welcome email. Some Mautic administrators choose to fire cron jobs as frequently as every one or two minutes to make the system catch up to changes even more quickly.
The IP lookup cron job fetches the lookup database from the data provider (by default, MaxMind GeoLite2 Free) that is used to match anonymous IP addresses to city and country.
The >/dev/null 2>&1 at the end of each line redirects any output on STDOUT or STDERR to /dev/null, preventing your root mailbox from filling up with cron output or error messages.
*/5 * * * * apache php /var/www/html/app/console mautic:segments:update >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:campaigns:rebuild >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:campaigns:trigger >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:email:fetch >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:messages:send >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:social:monitoring >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:webhooks:process >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:broadcasts:send >/dev/null 2>&1
*/5 * * * * apache php /var/www/html/app/console mautic:import >/dev/null 2>&1
30 2 * * sun apache php /var/www/html/app/console mautic:iplookup:download >/dev/null 2>&1
Site URL Not Correct Due To No mod_rewrite, or After Moving Mautic instance
If you forget to enable mod_rewrite by executing the command a2enmod rewrite on Ubuntu, or setting AllowOverride All for the DocumentRoot in your Apache configuration file on CentOS systems before installing Mautic, your Mautic Site URL may be set incorrectly.
The tell-tale sign of this problem is if your Site URL is detected by Mautic as https://mautic.example.com/index.php instead of https://mautic.example.com. After you have ensured mod_rewrite is now enabled (reflected by the pretty URLs working in your address bar), go to Configuration > System Settings in the dashboard, and modify Site URL.
Then be sure to clear the cache by running the command sudo -u <apache_user> php app/console cache:clear from your Mautic directory.
CORS Settings Not Set for All Domains/Subdomains, Including www & non-www
Also in the Configuration > System Settings dashboard you will find a toggle called CORS Settings. CORS stands for Cross-Origin Request Sharing. Since your Mautic instance is most likely installed on a subdomain of your primary URL such as https://mautic.example.com, when you embed the tracking pixel on your website https://example.com or https://www.example.com it is considered cross-origin.
Without all domains and subdomains listed under CORS Settings, the Mautic tracking pixel may malfunction. Be sure to include both the www and non-www versions of your website. It is a good idea to leave Restrict CORS set to “Yes” as that will reduce the prevalence of bots being tracked as anonymous lead by Mautic.
Max Upload Size for Mautic Assets
Setting the upload_max_size in php.ini as described earlier in this article is sufficient to allow large files, such as images, PDF ebooks, and media files to be uploaded as a Mautic asset. In addition to updating the PHP configuration on your server, you must also go to Configuration > Asset Settings in the Mautic dashboard to update the Maximum Size (MB) to the desired value — not to exceed the upload_max_size or post_max_size variables. We recommend between 64 to 128 megabytes for the typical Mautic instance.
Long “Wait Time Before Retrying Failed Action”
In Configuration > Campaign Settings, the default Wait Time Before Retrying Failed Action is set to 1 hour. Sometimes campaign actions fail to fire because the server was too busy, or the email transport temporarily could not be reached (e.g. for a Send Email action). We recommend changing this to 15 minutes instead of 1 hour so failed actions are reattempted as speedily as possible.
Email Gateway Sending Over SMTP, not API Transport
Each Mautic instance must be configured with a third-party gateway, such as Amazon SES, Elastic Email, SendGrid, SparkPost, Mailjet, or Mandrill to have email sending capabilities. Although your email service provider may provide the option of either connecting over conventional SMTP or using their API, always opt for the service-specific API option rather than configuring your email gateway as “Other SMTP” in Configuration > Email Settings within the Mautic dashboard.
Depending on the mail service, using the API transport entails either inputting the username and password credentials into Mautic, or a unique API key which is generated from the ESP’s dashboard.
You’ll thank yourself later when your mass emails are sending many times faster than using SMTP. “Other SMTP” is only good for testing, for example using a Gmail account to send less than 500 emails/day, or for advanced configurations where a Mail Transfer Agent (MTA) is running on the localhost, which forwards messages onward to an outgoing mail server for further processing.
Bounce/Unsubscribe Webhook Alerts Not Configured
Mautic provides two different methods for detecting bounces/unsubscribes, which are an inevitable fact of life for any email campaign. Lists get stale, with 20% of emails becoming invalid on average every year as people switch jobs or change ISPs.
One of these methods is called Monitored Inbox, which does exactly what it says on the tin. Mautic connects to the reply-to/return-path email inbox via IMAP to try and identify bounced emails and unsubscribe requests. It’s a good idea to have this setup under Configuration > Email Settings, but understand this is not the most accurate way of catching all the bounces and unsubscribes. Not all bounces/unsubscribes result in emails going back to the originating inbox, depending on the configuration of the receiving email server.
For Gmail or GSuite email accounts, use the following IMAP settings.
- 2 Factor Authentication and “Less Secure Apps” must be switched on.
- Create an app specific password (App and Device can be “Other”, type in “Mautic”).
Monitored Address: firstname.lastname@example.org
IMAP host: imap.gmail.com
IMAP Username: email@example.com
IMAP Password: <your app-specific password>
- Click “Test Connection and Fetch Folders.”
- Select “INBOX” for “Folder to Check” under the Bounces, Unsubscribe, and Contact Replies heading.
A far more accurate way to track bounces/unsubscribes is to use webhook alerts provided by Amazon SES, Elastic Email, SendGrid, SparkPost, MailJet, and Mandrill. This documentation article at Mautic.org clearly outlines how to enable webhooks with each ESP and test that they are correctly firing against the endpoint located on your Mautic server.
At the email gateway level, far more information can be detected from the receiving email server’s response such as whether a message has soft-bounced (the user’s inbox is full) or hard-bounced (inbox no longer exists). Current versions of Mautic don’t distinguish between soft and hard bounces in reports, but email addresses that have hard-bounced multiple times are automatically set as “Do Not Contact.” This protects your email reputation and prevents your sending IP or domain from ending up on a blacklist, as some overzealous email admins report any senders that repeatedly send to hard bounced addresses to clearinghouses such as Spamhaus. Once an IP or domain ends up on a blacklist, it can be difficult or nearly impossible to remove it, so setting up bounce/unsubscribe tracking correctly in the first place is extremely important.
Mautic Troubleshooting & Server Tuning by Autoize Experts
Confused what all of this technical mumbo-jumbo means? Get in touch with one of Autoize’s Mautic consultants who can tune your instance for optimum stability, performance, and security. We were the first Mautic-focused consultants on the scene in 2016 with the depth of technical knowledge to relieve you from the headaches of administering a Mautic instance in a cloud environment.
Contact us for a checkup of your Mautic instance today.