Fluent Mail Interface (PendingMail)

Purpose and Scope

This document describes the PendingMail class, which provides a fluent builder interface for configuring email recipients and locale before sending a Mailable instance. The PendingMail pattern allows developers to separate recipient specification from the Mailable definition itself, enabling reusable email classes that can be sent to different recipients without modification.

For information about creating Mailable classes, see Creating Mailable Classes. For details on the full mailable lifecycle and preparation process, see Mailable Lifecycle and Preparation. For queue integration, see Queue Integration.

Sources: src/PendingMail.php1-143 src/Mailer.php1-518

---

Overview

The PendingMail class acts as an intermediary between the Mailer and a Mailable instance. It temporarily stores recipient configuration (to, cc, bcc) and locale settings, then applies them to the Mailable just before sending. This pattern enables:

1. Separation of concerns: Mailable classes focus on content, while recipient specification happens at send time
2. Reusability: The same Mailable can be sent to different recipients
3. Fluent API: Chain methods for readable recipient configuration
4. Locale support: Automatic locale detection from recipient objects

Sources: src/PendingMail.php15-45 src/Mailer.php110-144

---

Creating PendingMail Instances

PendingMail instances are created through three methods on the Mailer class:

Method	Purpose	Returns
to(mixed $users, ?string $name = null)	Begin configuring "to" recipients	PendingMail
cc(mixed $users, ?string $name = null)	Begin configuring "cc" recipients	PendingMail
bcc(mixed $users, ?string $name = null)	Begin configuring "bcc" recipients	PendingMail

Each method:

1. Creates a new PendingMail instance with the Mailer reference
2. If both $users is a string and $name is provided, wraps them in an Address object
3. Calls the corresponding recipient method on PendingMail
4. Returns the PendingMail for method chaining

Sources: src/Mailer.php113-144 src/PendingMail.php42-45

---

Recipient Configuration Methods

The PendingMail class provides three fluent methods to configure recipients:

to(mixed $users)

Sets the "to" recipients of the message. The $users parameter accepts:

• A single email address string
• An Address instance
• An array of addresses
• Any object with recipient information

Additionally, if the $users object has a preferredLocale() method and no locale has been set yet, the method automatically calls locale($users->preferredLocale()) to configure the message locale based on the recipient's preference.

Sources: src/PendingMail.php60-69

cc(mixed $users)

Sets the "cc" (carbon copy) recipients of the message. Accepts the same parameter types as to() but does not trigger automatic locale detection.

Sources: src/PendingMail.php74-79

bcc(mixed $users)

Sets the "bcc" (blind carbon copy) recipients of the message. Accepts the same parameter types as to() and does not trigger automatic locale detection.

Sources: src/PendingMail.php84-89

All three methods return $this for method chaining:

Sources: src/PendingMail.php60-89

---

Locale Configuration

locale(string $locale)

Sets the locale for the message, which affects how the Mailable renders localized content. This is particularly useful for multi-lingual applications where emails need to be sent in the recipient's preferred language.

Sources: src/PendingMail.php50-55

Automatic Locale Detection

When using the to() method, PendingMail automatically checks if the recipient object has a preferredLocale() method. If found and no locale has been explicitly set, it automatically configures the locale:

This automatic detection enables sending localized emails without explicitly specifying locale when working with user models that implement locale preferences.

Sources: src/PendingMail.php60-69

---

Sending Methods

PendingMail provides four methods for dispatching emails, each delegating to the corresponding Mailer method after populating the Mailable with recipient data:

Method	Description	Behavior
send(MailableContract $mailable)	Send immediately or queue if ShouldQueue	Calls fill() then Mailer::send()
sendNow(MailableContract $mailable)	Force synchronous send	Calls fill() then Mailer::sendNow()
queue(MailableContract $mailable)	Queue for asynchronous sending	Calls fill() then Mailer::queue()
later(delay, MailableContract $mailable)	Queue with delay	Calls fill() then Mailer::later()

Send Flow Diagram

Sources: src/PendingMail.php94-128

Return Values

Method	Return Type	Notes
send()	?SentMessage	null if queued via ShouldQueue
sendNow()	?SentMessage	Always attempts synchronous send
queue()	mixed	Queue system response
later()	mixed	Queue system response

Sources: src/PendingMail.php94-128

---

Internal Fill Mechanism

The fill(MailableContract $mailable) method is the core internal mechanism that transfers recipient configuration from PendingMail to the Mailable. This method:

1. Calls to(), cc(), and bcc() on the Mailable with stored recipients
2. If a locale is configured, calls locale() on the Mailable
3. Returns the populated Mailable for immediate use

Fill Method Structure

The method uses tap() to apply all recipient methods in a chain while returning the final Mailable instance:

Sources: src/PendingMail.php133-142

---

Usage Patterns

Basic Single Recipient

This creates a PendingMail, sets the "to" recipient, and immediately sends the OrderShipped mailable.

Multiple Recipients with Different Types

All three recipient types can be configured before sending.

With Explicit Locale

Explicitly sets Spanish locale, overriding any automatic detection.

With User Object (Auto-locale Detection)

The PendingMail automatically calls $user->preferredLocale() and sets the mailable's locale to 'fr'.

Queue Operations

Sources: src/PendingMail.php94-128 src/Mailer.php113-144

---

Class Properties Reference

Property	Type	Purpose	Access
$mailer	MailerContract	Reference to Mailer instance	protected
$locale	?string	Message locale	protected
$to	mixed	"To" recipients	protected
$cc	array	"CC" recipients	protected
$bcc	array	"BCC" recipients	protected

Sources: src/PendingMail.php19-43

---

Conditionable Trait Integration

The PendingMail class uses the Conditionable trait, which provides conditional method chaining capabilities:

This allows for conditional recipient configuration without breaking the fluent chain.

Sources: src/PendingMail.php17

---

Method Chain Flow

The complete flow from Mailer method to email dispatch:

Sources: src/PendingMail.php1-143 src/Mailer.php113-144

---

Comparison: Direct Mailable vs PendingMail

Approach	Code	Use Case
Direct on Mailable	(new OrderShipped($order))->to($user)->send($mailer)	Recipient known at Mailable creation
Via PendingMail	$mailer->to($user)->send(new OrderShipped($order))	Reusable Mailable, recipient specified at send time

The PendingMail approach is particularly useful when:

• The same Mailable class is sent to different recipients
• Recipient configuration logic is complex (multiple cc/bcc)
• Working with dependency injection where Mailer is injected
• Locale needs to be determined from recipient object

Sources: src/PendingMail.php94-142 src/Mailer.php215-278