Queue Integration

This document explains how the mail system integrates with the queue system to enable asynchronous email sending. It covers automatic queue detection, manual queue methods, the SendQueuedMailable job wrapper, queue configuration, and job lifecycle management.

For information about the general message lifecycle and synchronous sending, see Message Lifecycle. For event handling during the send process, see Event System.

Overview

The mail system provides seamless integration with the queue system, allowing emails to be sent asynchronously rather than during the request lifecycle. This integration operates through three primary mechanisms:

1. Automatic Queue Detection: Mailables implementing ShouldQueue are automatically queued when sent
2. Manual Queue Methods: Explicit queue() and later() methods for controlled queue dispatch
3. Job Wrapper: The SendQueuedMailable class wraps mailables for queue processing

Sources: src/Mailer.php269-278 src/Mailable.php163-182 src/Mailable.php187-217

Automatic Queue Detection

When a mailable implements the ShouldQueue interface, the Mailer automatically detects this and queues the message instead of sending it synchronously. This detection occurs in the sendMailable() method:

The automatic detection logic in src/Mailer.php269-278:

• Checks if the mailable implements ShouldQueue
• Calls mailable->queue() instead of mailable->send()
• Returns null immediately since the message is queued, not sent

This allows developers to control queueing behavior through interface implementation rather than changing calling code.

Sources: src/Mailer.php269-278 src/Mailable.php187-201

Manual Queue Methods

The system provides explicit methods for queueing emails when automatic detection is not used or when specific queue behavior is needed:

Mailable Queue Methods

Method	Parameters	Purpose
queue()	QueueFactory $queue	Queue the mailable immediately
later()	DateInterval|DateTimeInterface|int $delay, QueueFactory $queue	Queue with delayed execution

Implementation in src/Mailable.php187-217:

• queue() checks for a delay property and delegates to later() if present
• Both methods extract connection and queue properties from the mailable
• Call newQueuedJob() to create the SendQueuedMailable wrapper
• Use QueueFactory to push the job to the appropriate queue

Mailer Queue Methods

Method	Parameters	Purpose
queue()	MailableContract $view, ?string $queue = null	Queue a mailable on default or specified queue
later()	DateInterval|DateTimeInterface|int $delay, MailableContract $view, ?string $queue = null	Queue with delay
onQueue()	?string $queue, MailableContract $view	Queue on specific queue
laterOn()	string $queue, DateInterval|DateTimeInterface|int $delay, MailableContract $view	Queue with delay on specific queue

Implementation in src/Mailer.php366-420:

• All methods accept only MailableContract instances (not arrays or strings)
• Set the mailer name via mailer($this->name)
• Delegate to the mailable's queue() or later() methods
• The onQueue parameter can override the mailable's default queue

Sources: src/Mailable.php187-217 src/Mailer.php366-420

SendQueuedMailable Job Wrapper

The SendQueuedMailable class wraps a mailable for queue processing. It acts as a bridge between the queue system and the mail system:

Job Construction

The constructor src/SendQueuedMailable.php46-61 extracts queue-related properties from the wrapped mailable:

Property	Source	Purpose
afterCommit	ShouldQueueAfterCommit interface or property	Wait for database transaction commit
connection	Property	Queue connection name
maxExceptions	Property	Maximum unhandled exceptions before failure
queue	Property	Queue name
shouldBeEncrypted	ShouldBeEncrypted interface	Encrypt job payload
timeout	Property	Job timeout in seconds
tries	Property	Maximum retry attempts

Job Execution

The handle() method src/SendQueuedMailable.php66-69 is invoked by the queue worker:

1. Receives a MailFactory instance via dependency injection
2. Calls $this->mailable->send($factory)
3. The mailable's send() method performs the actual email delivery synchronously

Sources: src/SendQueuedMailable.php1-121

Queue Configuration Properties

Mailables can define properties to configure queue behavior. These properties are automatically detected and applied by SendQueuedMailable:

Property Definitions

Queue Routing Properties:

• connection: Specifies which queue connection to use (e.g., 'redis', 'database')
• queue: Specifies the queue name within the connection (e.g., 'emails', 'high-priority')
• delay: Delays job execution by specified time (int seconds, DateInterval, or DateTimeInterface)

Retry Behavior Properties:

• tries: Maximum number of times the job should be attempted
• timeout: Maximum seconds the job can run before timing out
• maxExceptions: Maximum unhandled exceptions before marking as failed
• backoff: Wait time between retry attempts (property or method returning int|array)
• retryUntil: Absolute time deadline for retries (property or method returning DateTime)

Transaction Properties:

• afterCommit: If true, wait for database transactions to commit before queueing

Property Detection

The SendQueuedMailable constructor uses property_exists() to check for these properties on the mailable instance. Methods like backoff() and retryUntil() are checked using method_exists() at runtime.

Sources: src/SendQueuedMailable.php46-93 src/Mailable.php187-201

Job Middleware Support

Mailables can specify middleware that should be applied to the queued job. The newQueuedJob() method src/Mailable.php222-229 applies middleware from two sources:

Middleware Application Logic:

1. Check if mailable has a middleware() method
2. Merge result with $this->middleware property (if exists)
3. Pass combined array to SendQueuedMailable->through()

This allows mailables to apply rate limiting, throttling, or other middleware to control queue execution.

Sources: src/Mailable.php222-229

Job Lifecycle and Error Handling

The SendQueuedMailable class provides hooks for the complete job lifecycle:

Retry Configuration

Backoff Strategy

The backoff() method src/SendQueuedMailable.php74-81 determines wait time between retries:

• Returns null if not configured
• Checks for backoff property or backoff() method on the mailable
• Can return int (seconds) or array (progressive backoff)

Retry Deadline

The retryUntil() method src/SendQueuedMailable.php86-93 sets an absolute deadline:

• Returns null if not configured
• Checks for retryUntil property or retryUntil() method on the mailable
• Returns DateTime instance representing the deadline

Failure Handling

The failed() method src/SendQueuedMailable.php98-103 is called when the job permanently fails:

• Checks if the mailable has a failed() method
• Calls it with the exception that caused the failure
• Allows mailables to implement custom failure logic (logging, notifications, etc.)

Sources: src/SendQueuedMailable.php74-103

Queue Factory Integration

The mail system requires a QueueFactory instance to dispatch jobs. The Mailer class stores this factory and provides it to mailables:

Integration Points:

1. MailManager injects QueueFactory via setQueue() src/Mailer.php512-517
2. Mailer stores factory in $queue property src/Mailer.php60
3. Queue methods pass factory to mailable's queue() or later() methods src/Mailer.php366-420
4. Mailable uses factory to push SendQueuedMailable to queue src/Mailable.php197-200

The QueueFactory contract provides:

• connection(?string $name): Select queue connection
• pushOn(string $queue, object $job): Push job to named queue
• laterOn(string $queue, DateInterval|DateTimeInterface|int $delay, object $job): Push with delay

Sources: src/Mailer.php60 src/Mailer.php366-420 src/Mailer.php512-517 src/Mailable.php187-217

Encryption Support

Mailables can be encrypted in the queue by implementing the ShouldBeEncrypted interface. The SendQueuedMailable constructor src/SendQueuedMailable.php58 detects this interface and sets the shouldBeEncrypted property accordingly.

When shouldBeEncrypted is true, the queue system encrypts the serialized job payload, protecting sensitive data (email addresses, content, etc.) while the job is stored in the queue.

Sources: src/SendQueuedMailable.php38-58

Display Name

The displayName() method src/SendQueuedMailable.php108-111 returns the class name of the wrapped mailable. This is used by queue monitoring tools and logs to identify the job type, making it easier to track which mailable is being processed.

Sources: src/SendQueuedMailable.php108-111