Queue & Jobs System

MailTrixy provides three automation modes for processing background tasks, from shared hosting environments to dedicated servers with Supervisor.

3 Automation Modes

MailTrixy adapts to your hosting environment by offering three distinct modes for running background jobs. You can configure the active mode from the admin panel under Settings → Queue Configuration.

1. Middleware Mode (Shared Hosting)

Designed for shared hosting where you cannot run persistent processes. Jobs are processed during HTTP requests via middleware. This approach piggybacks on user traffic to process pending jobs.

Setting	Default	Description
max_jobs_per_request	3	Maximum number of jobs to process per HTTP request
time_limit	5 seconds	Maximum execution time for job processing per request
throttle_interval	60 seconds	Minimum time between processing batches to avoid CPU spikes

// config/mailtrixy.php
'queue' => [
    'mode' => 'middleware', // middleware | worker | scheduler
    'middleware' => [
        'max_jobs_per_request' => 3,
        'time_limit' => 5,
        'throttle_interval' => 60,
    ],
],

2. Queue Worker Mode (VPS/Dedicated)

The recommended mode for production deployments. Uses Laravel's built-in queue worker as a persistent daemon process managed by Supervisor. Provides immediate job processing and full concurrency support.

# Start the queue worker
php artisan queue:work --queue=default,email-sync,oauth-refresh,campaigns --tries=3 --timeout=90

3. Scheduler Mode (Cron-Based)

A middle-ground approach that uses Laravel's task scheduler triggered by a single cron entry. Jobs are processed every minute via a scheduled command.

# Add to crontab
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

All 13 Queue Jobs

MailTrixy ships with 13 dedicated job classes that handle all background processing tasks.

#	Job Class	Queue	Purpose
1	SyncEmailAccountJob	email-sync	Connects via IMAP and syncs new emails, folders, and read status for a single account
2	SendCampaignEmailJob	campaigns	Sends a single campaign email to one recipient with tracking pixels and unsubscribe links
3	SendScheduledEmailJob	default	Delivers emails that were composed and scheduled for a future date/time
4	ExecuteWorkflowJob	default	Runs the next step in a workflow execution, evaluates conditions, and dispatches actions
5	GenerateAIReplyJob	default	Generates an AI-powered reply draft using the configured provider and knowledge base context
6	SendAIReplyJob	default	Sends an approved AI-generated reply through the appropriate channel (email, Slack, Telegram)
7	AnalyzeSentimentJob	default	Runs sentiment analysis on incoming messages to classify urgency and customer satisfaction
8	ProcessKBDocumentJob	default	Parses uploaded documents, splits into chunks, generates embeddings for semantic search
9	ScrapeWebsiteJob	default	Crawls a website URL, extracts text content, and stores it as knowledge base documents
10	RefreshOAuthTokenJob	oauth-refresh	Refreshes expiring OAuth tokens for Gmail and Outlook accounts before they expire
11	RetryWebhookJob	default	Retries failed webhook deliveries with exponential backoff (max 5 attempts)
12	HandleFailedPaymentJob	default	Processes failed payment webhooks, sends dunning emails, and manages grace periods
13	WakeUpWorkflowJob	default	Resumes paused workflow executions after a delay step completes its wait period

4 Queue Channels

Jobs are distributed across four named queues to allow priority-based processing and resource isolation.

Queue Name	Priority	Jobs	Description
default	Normal	8 jobs	General-purpose queue for workflows, AI, knowledge base, webhooks, and scheduled emails
email-sync	High	1 job	Dedicated queue for IMAP sync to ensure emails are pulled frequently without delay
oauth-refresh	Critical	1 job	Highest priority queue to ensure OAuth tokens are refreshed before they expire
campaigns	Low	1 job	Isolated queue for bulk campaign sending to prevent it from blocking other operations

Supervisor Configuration

For production deployments using the Queue Worker mode, configure Supervisor to keep your workers running and automatically restart them if they fail.

; /etc/supervisor/conf.d/mailtrixy-worker.conf

[program:mailtrixy-default]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mailtrixy/artisan queue:work --queue=default --sleep=3 --tries=3 --timeout=90
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/mailtrixy/storage/logs/worker-default.log
stopwaitsecs=3600

[program:mailtrixy-email-sync]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mailtrixy/artisan queue:work --queue=email-sync --sleep=3 --tries=3 --timeout=120
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/mailtrixy/storage/logs/worker-email-sync.log
stopwaitsecs=3600

[program:mailtrixy-oauth]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mailtrixy/artisan queue:work --queue=oauth-refresh --sleep=10 --tries=5 --timeout=30
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/mailtrixy/storage/logs/worker-oauth.log

[program:mailtrixy-campaigns]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mailtrixy/artisan queue:work --queue=campaigns --sleep=5 --tries=3 --timeout=60
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/mailtrixy/storage/logs/worker-campaigns.log

After creating the configuration, reload Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start mailtrixy-default:*
sudo supervisorctl start mailtrixy-email-sync:*
sudo supervisorctl start mailtrixy-oauth:*
sudo supervisorctl start mailtrixy-campaigns:*

Failed Job Handling

MailTrixy automatically handles failed jobs with configurable retry logic and monitoring.

• Automatic retries — Each job is retried up to 3 times with exponential backoff (gradually increasing the wait time between retries to avoid overloading the system) (30s, 120s, 480s).
• Failed job table — Jobs that exceed retry limits are stored in the failed_jobs table with the exception message and payload.
• Admin notifications — The admin receives an email notification when a job permanently fails.
• Manual retry — Failed jobs can be retried from the admin panel or via artisan commands.

# View failed jobs
php artisan queue:failed

# Retry a specific failed job
php artisan queue:retry 5

# Retry all failed jobs
php artisan queue:retry all

# Delete a failed job
php artisan queue:forget 5

# Flush all failed jobs
php artisan queue:flush

Job Monitoring

The admin dashboard provides real-time monitoring of the queue system, including:

• Queue depth — Number of pending jobs per queue displayed on the admin dashboard.
• Processing rate — Jobs processed per minute with historical graphs.
• Failed job count — Total failed jobs with one-click retry capability.
• Worker status — Active worker processes and their current job (when using Queue Worker mode).
• Last sync timestamps — Per-account last email sync time displayed in the email accounts list.
• Health checks — Automatic alerts when queue depth exceeds configurable thresholds (default: 100 jobs).

For advanced monitoring, MailTrixy supports integration with Laravel Horizon (optional, requires Redis). When Horizon is installed, it replaces the built-in monitoring with its full-featured dashboard.