How to Properly Set Up Your Mautic Cron Jobs: An In-Depth Guide

Do you need to set up cron jobs for Mautic, but have no clue what cron jobs are, or which cron jobs are relevant? Are you wondering what correct cron job schedules are?

Then, we'd like to welcome you to our comprehensive guide on Mautic cron jobs. Whether you're a Mautic newbie, or a seasoned pro looking to sharpen your skills, this blog post will guide you through the ins and outs of Mautic cron jobs. By the end, you'll not only understand what these cron jobs do, but also how to use them effectively.

Let's start with the primer on cron jobs.

Primer on Cron Jobs

Cron jobs are an integral part of Mautic. They handle numerous essential tasks that ensure the smooth running of your marketing automation processes. To set them up correctly, you need to understand them.

What are Cron Jobs?

In the world of Unix-based systems, cron is a time-based job scheduler that automates tasks. These tasks, known as "cron jobs," are executed at fixed times, dates, or intervals. In the context of Mautic, cron jobs are used to automate a variety of tasks, such as updating segments, sending emails, and triggering campaign events.

Why are Cron Jobs Important in Mautic?

Mautic relies heavily on cron jobs to perform various tasks. Without these automated processes, Mautic would not function correctly. Cron jobs ensure that your segments are updated, your emails are sent, and your campaigns are triggered when they should be. They also perform maintenance tasks such as cleaning up old data to keep your Mautic instance running smoothly.

How Do I Set Cron Jobs Up?

To set up your cron jobs, you need to edit the crontab. Normally there are two ways to edit the crontab. Either your hosting provider gives you ssh access, or they have a web interface where you set up your cron jobs.

If you have ssh access simply type crontab -e in your terminal. Otherwise, please check your hosting documentation.

• cPanel: https://blog.cpanel.com/how-to-configure-a-cron-job
• Plesk: https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/scheduling-tasks.64993/

Each line of your crontab file represents a cron job, and looks like this:

# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of the month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ ┌───────────── day of the week (0 - 6)
# │ │ │ │ │               (Sunday to Saturday;
# │ │ │ │ │               7 is also Sunday on some systems)
# │ │ │ │ │
# │ │ │ │ │
  * * * * * <command to execute>

The five asterisks before the command each represent a unit of time. From left to right, they are:

1. Minute (0 - 59)
2. Hour (0 - 23)
3. Day of the month (1 - 31)
4. Month (1 - 12)
5. Day of the week (0 - 7) (where 0 [and 7, if available] represents Sunday, 1 is always Monday)

Here are a few examples:

• 0 0 * * * command : This means the command will run at midnight (at minute 0 and hour 0), every day.
• 0 12 * * MON command : This means the command will run at noon every Monday.
• */10 * * * * command : This means the command will run every 10 minutes.
• 10,20 * * * * command : This means the command will run at the 10th and 20th minute of every hour, every day.
• 0 0 1 * * command : This means the command will run at midnight on the first day of every month.

The asterisk (*) is a wildcard that means "every". So, if you put an asterisk in the minute field, that means "every minute". If you put an asterisk in the day of the month field, that means "every day of the month", and so on.

If you put a slash / and a number behind an asterisk, that means "every X [time unit]". While 10 * * * * means "execute the command at the 10th minute of every hour of every day", */10 * * * * tells cron to run the command every 10 minutes.

You can comma separate values in time units. 5,10,15,22 * * * * means at the 5th, 10th, 15th and 22nd minute of every hour, every day.

Mautic's Essential Cron Jobs

Mautic relies on (at least) three core commands to be run automatically:

• Segment update: This cron job updates contacts in your segments based on the segment filters. The command for this cron job is mautic:segments:update.
• Campaign update: This cron job rebuilds campaigns based on their conditions. The command for this cron job is mautic:campaigns:update.
• Campaign trigger: This cron job triggers scheduled campaign events. The command for this cron job is mautic:campaigns:trigger.

It is highly recommended that you stagger these three required cron jobs. This prevents that Mautic runs them at the same time, which could lead to errors—especially in your campaign actions.

The recommendation is to run the commands every fifteen minutes and keep a puffer of five minutes between the commands. This ensures that one command has sufficient time to finish.

The Perfect Cron Job Setup for Mautic

Tired of waiting 15 minutes between Mautic’s cron job script executions? Are you concerned about the effectiveness of your marketing campaigns, because of this delay? Supercharge your Mautic cron jobs and run them with almost no delay. Our performance optimized script runs every minute, removing alm…

Mautic RoundupTobias

Your crontab could look like this:

0,15,30,45 * * * * php /path_to_mautic_folder/bin/console mautic:segments:update
5,20,35,50 * * * * php /path_to_mautic_folder/bin/console mautic:campaigns:update
10,25,40,55 * * * * php /path_to_mautic_folder/bin/console mautic:campaigns:trigger

Important Message Sending Cron Jobs

Mautic uses three commands to handle its message sending functionality. You should configure all three. Otherwise, some emails/messages get stuck in a queue.

mautic:emails:send

mautic:emails:send processes the email queue in Mautic. It's critical to run this cron job if you've configured Mautic to store emails to be sent in an email queue:

Without running this job, campaign emails won't get sent—if queued. The queued email system is beneficial for managing a large number of emails and ensuring your server isn't overwhelmed.

• Recommended Schedule: As fast as possible, but ensure sending emails won't overlap as this could result in emails sent twice (or even worse: more). E.g. every two minutes.
• Crontab Command: *\2 * * * * php /path_to_mautic_folder/bin/console mautic:emails:send

Additional Parameters:

• --message-limit[=MESSAGE-LIMIT]: Limit number of messages sent at a time. This is helpful to avoid the command running to long.
• --time-limit[=TIME-LIMIT]: Limit the number of seconds per run. This is helpful to avoid the command running to long.
• --do-not-clear: Prevents Mautic to delete messages that failed after a specific time. By default, failed messages older than a specific time (the --recover-timeout setting, to be precise) will be attempted one more time. If sending fails again Mautic will delete it. With this option, Mautic will continue to attempt sending failed messages.

mautic:broadcasts:send

mautic:broadcasts:send is responsible for sending out scheduled broadcasts. Broadcasting is a useful feature for sending mass emails to your segments, like newsletters or announcements.

If you're using the scheduling feature for your broadcasts, you must run this cron job; otherwise, your broadcasts will not be sent.

• Recommended Schedule: As fast as possible, but ensure sending emails won't overlap as this could result in emails sent twice (or even worse: more). E.g. every two minutes.
• Crontab Command: *\2 * * * * php /path_to_mautic_folder/bin/console mautic:broadcasts:send

Additional Parameters:

• --batch[=BATCH] : Limit how many messages to send in one run. This is helpful to avoid the command running to long.
• --limit[=LIMIT]: Limit how many contacts to load from database to process. This is helpful to avoid the command running to long.
• The difference between batch and limit is the following: limit limits how many contacts get processed. One contact could receive more than one email, because two, three or more are scheduled to send to him. batch is a somewhat “harder” limit, limiting the number of emails to be sent.
• --id[=ID]: The ID for a specific channel (i.e., email) to process broadcasts for pending contacts. You can use this so prioritize. But you need to process all channels at some point, otherwise some message get stuck in the queue.
• --min-contact-id[=MIN-CONTACT-ID] and --max-contact-id[=MAX-CONTACT-ID]: With those commands you can set up contact batches. E.g. one run process all contacts with id 0 to 999 the other 1000 to 1999. With this you could process sending to contacts safely in parallel.

mautic:messages:send

mautic:messages:send is responsible for sending messages queued because of frequency rules. If you've set up system-wide frequency rules (such as limiting to two emails per contact per day) or if a contact has set their own preferences, Mautic will push any messages that exceed the frequency into a queue.

Frequency rules might queue campaign messages that are marked as "Marketing Emails" (and not transactional emails).

By using this feature, you respect your contacts' preferences and avoid overloading them with emails. But without mautic:messages:send your mails might get stuck in a queue without getting send.

• Recommended Schedule: As fast as possible, but ensure sending emails won't overlap as this could result in emails sent twice (or even worse: more). E.g. every two minutes.
• Crontab Command: *\2 * * * * php /path_to_mautic_folder/bin/console mautic:messages:send

mautic:email:fetch

mautic:email:fetch does two jobs:

1. It is used to fetch and process messages such as bounces and unsubscribe “requests” (via spam reporting). It is crucial to set this up to keep your sender reputation and comply with data/privacy laws—but only (!) if your email service provider won't forward these to Mautic.
2. It is used to fetch answers from your contacts. You need to set this up if you want to know if contacts responded to your emails. See this post, which goes into depth for this:

• Recommended Schedule: As needed, but setting it to run every 5 minutes might be a good idea for bounce management. For managing contact replies, once per hour should be sufficient.
• Crontab Command: */5 * * * php path_to_mautic_folder/bin/console mautic:emails:fetch
  

Optimizing Mautic's Performance with Cronjobs

If you grow, maintaining Mautic's efficiency can suffer a bit as Mautic processes a load of data. Luckyli, there Mautic provides commands to clean data and keep performance up. You can set these up in cron jobs.

mautic:unusedip:delete

Mautic's performance can degrade over time (partly) due to an accumulation of unused IP addresses in the database. This is particularly true for websites with high traffic, where numerous anonymous contacts get created but do not register. Running the mautic:unusedip:delete cronjob periodically helps clear out this unnecessary data, thereby improving Mautic's speed and efficiency.

• Recommended Schedule: Preferably during low-activity hours, like 1 AM, once a week (e.g., on Sundays).
• Crontab Command: 0 1 * * 0 php path_to_mautic_folder/bin/console mautic:unusedip:delete

mautic:maintenance:cleanup

Mautic's tracking feature collects extensive data about your contacts. While this information is invaluable for understanding your audience, it can result in a bloated database over time. The mautic:maintenance:cleanup cronjob helps prune this data. It removes information that is no longer necessary or relevant, such as a contact's page visits from a year ago.

• Recommended Schedule: Daily
• Crontab Command: 0 2 * * * php path_to_mautic_folder/bin/console mautic:maintenance:cleanup

Additional Parameters:

• --gdpr: Delete data to comply with GDPR requirements.
• --days-old=90: Purge records older than this number of days. Default is set to 365 days.

mautic:webhooks:process

Mautic can send webhooks to other applications. If you're sending numerous webhooks or have limited server resources, it could potentially slow down Mautic. The mautic:webhooks:process cronjob helps manage this by queuing up webhooks for processing at a later time.

You need webhook queuing in your configuration:

• Recommended Schedule: Custom. You need to meet your requirements. Every hour might be a good start.
• Crontab Command: * \1 * * * php path_to_mautic_folder/bin/console mautic:mautic:webhooks:process

Additional Parameters:

• -i, --webhook-id[=WEBHOOK-ID] : Process the queued payload for a specific webhook.

Additional Cron Jobs

There are a couple more Mautic commands that might be set up as cron jobs. None of these are integral for Mautic to function properly. So, we just name them here. If you need to know more consult the documentation or php mautic/bin/console help [command].

Automations

• mautic:import: Import contacts in the background. Set it up if you need it.
• mautic:reports:scheduler: You can create and send reports in the background. This is useful if you have a large dataset. It should be running at night.

CRM - Customer Relationship Management

• mautic:integration:pushleadactivity sends your contacts to a CRM of your choice. If you need it, let it run every hour or so.
• mautic:integrations:fetchleads fetches leads from another CRM and adds them as contacts to your Mautic database. If you need it, let it run every hour or so.

Keeping Tabs on Your Cron Jobs

If you're like me, you want to know if your jobs are running as expected, and if not, you want to be informed about any issues that arise—as soon as possible.

Fortunately, cron provides built-in features that allow you to keep tabs on your tasks. Specifically, it lets you create log files to track the output of your jobs, and it can notify you via email when jobs encounter errors.

How to Create Log Files

Normally, cron silently executes the jobs it has to do. As it runs autonomously you won't see any output. This gives you no insight in what happened, which is bad, in case something is off.

Creating log files with cron jobs is, therefore, a good practice as it helps you track and troubleshoot the tasks that are being automated. Here's how you can do it:

You can create a log file for this cron job by appending >> /path/to/mautic.cron.log. So, 0,15,30,45 * * * * php /path/to/mautic/bin/console mautic:segments:update would become 0,15,30,45 * * * * php /path/to/mautic/bin/console mautic:segments:update >> /path/to/mautic.cron.log.

How to Get Error Notifications Per Email

While logs are fine, they are silent, too. You need to know that you have to look into them after all. A notification in case of an error would be nice, right?

Fortunately, cron offers to email you the output of a command, all you need to do is to add the line MAILTO=your@email.com in your crontab. For example:

MAILTO=mautic.cronerror@mydomain.com
0,15,30,45 * * * * php /path/to/mautic/bin/console mautic:segments:update >> /path/to/mautic.cron.log
5,20,35,50 * * * * php /path/to/mautic/bin/console mautic:campaigns:update >> /path/to/mautic.cron.log
10,25,40,55 * * * * php /path/to/mautic/bin/console mautic:campaigns:trigger >> /path/to/mautic.cron.log

With this, cron would email you if any of the commands fail—every time they fail. For further information, read this, this or this.