Mail Component

The Mail Component provides a Laravel-style email sending system for Hyperf applications. It wraps Symfony Mailer to provide a fluent API for constructing and sending emails through multiple transport backends (SMTP, SES, Mailgun, Postmark, etc.). The component supports view rendering, Markdown templates, file attachments, locale-based content, and comprehensive testing utilities.

For HTTP-based communication, see HTTP Client - Request Building and Execution. For multi-channel notifications that use mail as one delivery method, see Notification System.

Architecture Overview

The mail system consists of three primary components: MailManager for transport configuration and mailer instantiation, Mailable for building email messages, and Message for low-level Symfony Email manipulation.

Sources: src/mail/src/MailManager.php1-460 src/mail/src/Mailable.php1-100

MailManager and Transport Factory

The MailManager class serves as the central factory for creating and managing mailer instances. It resolves transport configuration from mail.php and instantiates appropriate Symfony Mailer transports.

Mailer Resolution Process

The manager dynamically routes to transport creation methods based on the transport configuration key. For example, transport: 'smtp' routes to createSmtpTransport() src/mail/src/MailManager.php94-111 Each creation method constructs the appropriate Symfony Mailer transport with configuration-specific options.

Sources: src/mail/src/MailManager.php76-196 src/mail/src/MailManager.php449-459

Transport Configuration Methods

Transport Type	Creation Method	Underlying Class	Configuration Keys
SMTP	createSmtpTransport()	EsmtpTransport	host, port, username, password, encryption, scheme
Sendmail	createSendmailTransport()	SendmailTransport	path
AWS SES	createSesTransport()	SesTransport	key, secret, region, version, options
AWS SES V2	createSesV2Transport()	SesV2Transport	key, secret, region, version, options
Mailgun	createMailgunTransport()	MailgunTransportFactory	secret, domain, endpoint, scheme
Postmark	createPostmarkTransport()	PostmarkApiTransport	token, message_stream_id
Log	createLogTransport()	LogTransport	name, group
Array	createArrayTransport()	ArrayTransport	(no config)
Failover	createFailoverTransport()	FailoverTransport	mailers[]
Roundrobin	createRoundrobinTransport()	RoundRobinTransport	mailers[]

Custom transports can be registered via extend() src/mail/src/MailManager.php142-147 which stores a closure in customCreators[] that the manager checks before dispatching to built-in creation methods.

Sources: src/mail/src/MailManager.php200-417

SMTP Transport Configuration

SMTP is the most commonly used transport. The createSmtpTransport() method constructs an EsmtpTransport via EsmtpTransportFactory and configures additional options:

The scheme is automatically determined based on encryption and port settings src/mail/src/MailManager.php200-223 If encryption is 'tls' and port is 465, the scheme becomes 'smtps'; otherwise 'smtp'. The configureSmtpTransport() method applies additional socket options like source_ip and timeout if the transport uses a SocketStream src/mail/src/MailManager.php228-243

Sources: src/mail/src/MailManager.php200-243

AWS SES Transport

SES transports require AWS SDK credentials. The createSesTransport() method merges configuration from services.ses with mailer-specific config, adds credentials if key and secret are provided, and instantiates SesClient src/mail/src/MailManager.php258-272:

The V2 variant uses SesV2Client instead, following the same pattern src/mail/src/MailManager.php277-291

Sources: src/mail/src/MailManager.php258-303

Global Address Configuration

After creating a Mailer instance, the manager applies global addresses from configuration src/mail/src/MailManager.php191-193:

The setGlobalAddress() method checks both mailer-specific and global configuration, converting address arrays with ['address' => ..., 'name' => ...] format into method calls like alwaysFrom(), alwaysReplyTo(), etc. src/mail/src/MailManager.php437-444

Sources: src/mail/src/MailManager.php170-196 src/mail/src/MailManager.php437-444

Mailable Class Structure

The Mailable base class provides a fluent interface for building email messages. Applications extend this class to define specific emails.

Core Properties and State

All properties are public, enabling direct access during testing and debugging src/mail/src/Mailable.php54-157

Sources: src/mail/src/Mailable.php47-161

Message Building Workflow

The send() method orchestrates the entire message building process:

The withLocale() wrapper temporarily changes the translator locale during message building src/mail/src/Mailable.php226-242 The buildViewData() method merges viewData[] with public properties from the mailable instance via reflection src/mail/src/Mailable.php247-262

Sources: src/mail/src/Mailable.php186-205 src/mail/src/Mailable.php226-242 src/mail/src/Mailable.php247-262

Setting Recipients and Addresses

Recipient methods follow a consistent pattern via setAddress():

Recipient Methods

Method	Property	Purpose	Global Method
from(address, name)	from[]	Sender	alwaysFrom()
to(address, name)	to[]	Primary recipients	alwaysTo()
cc(address, name)	cc[]	Carbon copy	alwaysCc()
bcc(address, name)	bcc[]	Blind carbon copy	alwaysBcc()
replyTo(address, name)	replyTo[]	Reply-to address	alwaysReplyTo()

Each method accepts:

• A string email address
• An array ['email@example.com' => 'Name']
• An object with email and name properties
• An array of any of the above

The to() method additionally checks for a preferredLocale() method on the recipient object and sets the mailable's locale accordingly src/mail/src/Mailable.php309-316

Sources: src/mail/src/Mailable.php293-372

Address Resolution

The setAddress() method normalizes all address formats into a consistent internal structure. It handles arrays, objects, and strings, converting them to Address objects internally.

Checking methods like hasTo(), hasCc(), etc., use hasRecipient() internally to compare addresses, supporting partial matching by email or full matching with name.

Sources: src/mail/src/Mailable.php293-372

Content and View Rendering

The mailable supports four content specification methods: view templates, Markdown templates, raw HTML, and plain text.

View Rendering Methods

Priority order: markdown > html > view. If textView is set alongside view, both HTML and text versions are included in the result array.

Sources: src/mail/src/Mailable.php396-433

View Data Building

The buildViewData() method constructs template variables from three sources src/mail/src/Mailable.php247-262:

1. Explicit data: viewData[] property set via with() or constructor
2. Static callback: Mailable::$viewDataCallback if registered
3. Public properties: All public properties from the mailable instance via reflection

This design enables clean mailable classes where you simply define public properties and they automatically become available in templates. The filter excludes properties defined in the Mailable base class itself.

Sources: src/mail/src/Mailable.php247-262

Attachment System

The mailable supports three attachment types: file paths, in-memory data, and storage disk files.

Attachment Types and Methods

Each storage array maintains unique attachments based on identifying keys (file path, data+name, or disk+path+name) src/mail/src/Mailable.php463-546

Sources: src/mail/src/Mailable.php452-581

Attachment Building Process

During message building, buildAttachments() iterates through all three attachment arrays and applies them to the Symfony Message object:

1. File attachments (attachments[]): Calls attachFromPath() with file path and options
2. Raw attachments (rawAttachments[]): Calls attachData() with data, name, and options
3. Disk attachments (diskAttachments[]): Retrieves file from storage disk via FilesystemFactory, then attaches

Options can include:

• as: Override filename
• mime: MIME type
• Additional Symfony attachment options

Sources: src/mail/src/Mailable.php452-581

Attachable Contract

The Attachable interface allows objects to define how they should be attached to emails. Implementors provide a toMailAttachment() method that returns an Attachment instance. The Attachment class provides flexible attachment strategies via attachWith(), which accepts callbacks for both file-based and data-based attachment patterns.

Sources: src/mail/src/Mailable.php452-469

Locale and Internationalization

The mailable supports per-message localization via the locale() method:

The withLocale() wrapper ensures the translator is temporarily set to the message's locale, then restored after building src/mail/src/Mailable.php226-242 This enables translation keys in view templates to resolve to the correct language.

Additionally, to() checks if the recipient object has a preferredLocale() method and automatically sets the mailable's locale if none was explicitly specified src/mail/src/Mailable.php311-313

Sources: src/mail/src/Mailable.php226-242 src/mail/src/Mailable.php269-274 src/mail/src/Mailable.php309-316

Advanced Features

Tags and Metadata

The mailable supports tags and metadata for tracking and categorization, particularly useful with services like Mailgun and Postmark:

• tag(string): Add a single tag
• tags(array): Add multiple tags
• metadata(string, mixed): Add key-value metadata

These are applied via buildTags() and buildMetadata(), which add TagHeader and MetadataHeader instances to the Symfony message src/mail/src/Mailable.php199-200

Sources: src/mail/src/Mailable.php148-156

Priority Setting

The priority(int) method sets message priority (1-5, where 1 is highest):

The callback is executed during runCallbacks() in the message building pipeline src/mail/src/Mailable.php281-288

Sources: src/mail/src/Mailable.php281-288

Custom Callbacks

Applications can register custom callbacks via callbacks[] that execute during message building. Each callback receives the Message instance and can perform arbitrary modifications.

Sources: src/mail/src/Mailable.php126

Testing Support

The mailable provides comprehensive testing capabilities:

Assertion Methods

Method	Purpose
hasFrom(address, name)	Check sender
hasTo(address, name)	Check primary recipient
hasCc(address, name)	Check CC recipient
hasBcc(address, name)	Check BCC recipient
hasReplyTo(address, name)	Check reply-to
hasSubject(subject)	Check subject line
hasAttachment(file, options)	Check file attachment
hasAttachmentFromStorage(path, name)	Check storage attachment
hasAttachedData(data, name)	Check in-memory attachment

All assertion methods support flexible matching—partial email matching, full email+name matching, or object-based matching.

Sources: src/mail/src/Mailable.php301-587

ArrayTransport for Testing

The ArrayTransport captures sent messages without actually sending them, enabling inspection in tests. Configure a mailer with transport: 'array' in test configuration src/mail/src/MailManager.php414-417

Sources: src/mail/src/MailManager.php414-417

Integration with Notification System

The mail component serves as a delivery channel for the notification system. The notification-mail package provides a MailChannel that converts notification instances into mailable messages. When a notification is sent via the mail channel, it creates a Mailable instance and sends it through the configured mailer.

For details on multi-channel notifications, see Notification System.

Sources: Referenced from high-level architecture diagram