Mautic cron jobs and email queue setup

The most useful way to troubleshoot a Mautic broadcast is to follow it stage by stage, because each stage fails differently and produces different symptoms. The sequence starts with the scheduler, which runs the segment update job. That job refreshes segment membership, so the contact list reflects the latest field values, tags and behavior. Next, the broadcasts command reads the segment attached to a segment email and selects the contacts who qualify at that moment. Each stage depends on the one before it. If membership is stale, the broadcast addresses the wrong people, and no later stage will notice. When queueing is enabled, the broadcasts command places messages on the queue instead of sending them directly. The messenger consumer then takes messages off the queue in batches and hands each one to the mail transport you have configured. Mautic does not decide how the message is delivered after that point; the configured sending service does. The team must confirm the mail transport configuration for its own provider, including credentials, sending limits, bounce handling and any provider-side throttling. Those settings sit outside the cron schedule, and a correct schedule cannot compensate for a transport that rejects or delays messages. Stalls and duplicates appear at predictable points. The segment update can fall behind if it runs against a large dataset, so the broadcast selects from outdated membership. The broadcasts command can select a large audience and fill the queue faster than the consumer drains it. The consumer can stop if its process is not supervised, leaving messages waiting without any error in the mail log. Duplicate sends most often come from overlapping runs: if a broadcasts job is still working when the next scheduled run starts, both can select the same contacts before either has finished. Staggering the jobs and confirming that each run completes before the next begins reduces this risk. A backlog in the queue and a stopped scheduler look similar from the marketing side, since the email simply does not arrive, but they need different responses. A backlog means the scheduler ran, messages were queued, and the consumer is either slow or not processing them. You check queue depth and consumer status. A stopped scheduler means no new messages are being created at all, so the queue may be empty while segments and campaigns quietly stop updating. You check the cron log for the last successful run of each job. Confirm with your own team which of these two conditions your monitoring would catch first, and who receives the alert.

The point of this test plan is to prove two things before a large send goes out: each scheduled Mautic job runs on its intended cadence without overlapping itself, and a broken worker produces a visible backlog rather than duplicate or lost emails. Run these checks in a staging copy that mirrors the production cron schedule, the production messenger setup and a non-production mail transport, so a test cannot reach real contacts. Start with the scheduled jobs. Confirm that the segment update, campaign update and campaign trigger commands each appear in the scheduler on the staggered times you planned, and that each one writes a start and finish entry to its log. Then force an overlap: start a long-running job by hand while the same command is still active, and check that the second invocation exits without processing contacts. Mautic's cron documentation expects jobs to be staggered, so a second run starting while the first is active is the most common cause of double processing. Record which lock or process check Mautic uses in your version, and confirm it with the vendor or the release notes rather than assuming it. Next, test the broadcast path with a small test segment of internal addresses. Include a few contacts with a known name and an address you can read, and confirm that the broadcasts command sends exactly one message to each recipient. Compare the sent count in the dashboard, the messenger queue and the mail provider's log. Any recipient receiving two messages means the batch limit, the cron overlap or the queue retry settings need correction before the real send. Then test the queue. Stop the messenger consumer, trigger a broadcast and watch the queue depth grow. Messages should accumulate without being dropped or marked as sent. Restart the consumer and confirm the backlog drains to zero and that the recipient count still matches the test segment. Finally, simulate a failed job, for example by pointing the mail transport at an unreachable host for one run, and check that the failure appears in the Mautic logs and in your monitoring, that the backlog stays visible, and that no message is sent twice after the transport is restored. A safe failure looks like this: no recipient receives a duplicate, the backlog is visible in queue monitoring, and the log names the job and the error. Recovery should follow a written runbook: fix the cause, confirm the transport, restart the consumer, let the backlog drain, then reconcile sent counts against the segment. Ask any implementation partner to deliver this runbook and the test evidence as part of the scope, and confirm the exact commands and monitoring tools with the Mautic version you run.

Once the Mautic cron jobs and the messenger consumer are running in production, the team's job shifts from building the pipeline to keeping it honest. The first routine is monitoring, and it should answer four questions every day: did each scheduled command finish, how long did it take, is anything waiting in the queue, and is the consumer still alive. Record the start and end time of each segment update, campaign update, campaign trigger and broadcast run, and alert when a run overlaps the next one or stops reporting. Queue depth matters just as much. A growing backlog during a large send usually means the consumer is too slow, has stopped, or is being starved by other jobs on the same host, and the team should know which of these it is before the send window closes.

Deliverability signals come from outside the server. Ask your sending provider to report bounce, complaint and failure rates per sending domain and per broadcast, and agree on thresholds that pause a campaign for review. Mautic will show what it attempted to send, but the provider shows what was accepted and what was rejected, so both views need to be compared. Also watch disk space in the Mautic log directory and the Supervisor log location. Verbose logging on a busy install can fill a volume quickly, and a full disk can stop cron output and queue processing without an obvious error in the Mautic interface. Confirm the log rotation and retention settings with your platform team, since the right retention depends on your compliance and incident response needs.

Backups need three parts. Back up the Mautic configuration file and any environment-specific settings, the Supervisor program definitions for the messenger consumer, and the scheduler definitions, whether that is the system crontab, a container job definition or another mechanism. Back up the database on a schedule that matches how often contacts and campaign state change, and test restores into a separate environment rather than assuming the dump is usable. Store the backups where the consumer and cron host cannot silently overwrite them. Ask your team to confirm restore time objectives and retention periods in writing, because those choices determine how much queued email or campaign history you can recover.

The runbook is what lets someone other than the original builder act at 2 a.m. It should cover restarting the consumer and cron jobs in order, pausing a broadcast before it reaches more contacts, and clearing or replaying the queue without sending duplicate email. Each step needs an owner, the command or console action, and a check that proves it worked. Replaying queued messages is the riskiest action, so define who can approve it and how the team confirms which messages were already accepted by the provider. Finally, schedule a recheck of cron and consumer settings at every Mautic upgrade. Mautic follows a monthly patch, quarterly minor and two-year major release cadence, so changes can arrive often. Confirm version-specific behavior for cron and messenger settings in the release notes for the exact version you run, and record the result in the runbook.