# Queue & Jobs System

For non-technical users: Queues handle background tasks like syncing emails, sending campaigns, and processing AI replies. On shared hosting, MailTrixy uses a simple cron job to process these automatically — no extra setup needed. This page covers advanced configuration for VPS and dedicated servers.

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.