Mail Messages

This document describes the mail message formatting system used by the notification channels. The MailMessage and SimpleMessage classes provide a fluent API for constructing email notification content, including structured text, action buttons, attachments, and rendering to HTML.

For information about sending mail messages through the notification system, see Mail Channel. For other message types, see Slack Messages (Legacy Attachments), Slack Block Kit, and Broadcast Messages.

---

Class Hierarchy and Structure

The mail message system consists of two primary classes that work together to construct email content:

Sources: src/Messages/SimpleMessage.php1-231 src/Messages/MailMessage.php1-333

---

SimpleMessage Base Class

SimpleMessage provides a structured format for notification content with a consistent layout pattern: greeting, intro lines, action button, and outro lines.

Content Structure

The class organizes content into distinct sections:

Property	Type	Description
level	string	Notification level: 'info', 'success', or 'error'
subject	string|null	Email subject line
greeting	string|null	Opening greeting text
salutation	string|null	Closing salutation text
introLines	array	Content lines before the action button
outroLines	array	Content lines after the action button
actionText	string|null	Call-to-action button label
actionUrl	string|null	Call-to-action button URL
mailer	string|null	Named mailer configuration to use

Sources: src/Messages/SimpleMessage.php12-55

Building Message Content

Sources: src/Messages/SimpleMessage.php58-202

Level Methods

The notification level affects visual styling in rendered templates:

• success() - Sets level to 'success' for positive notifications
• error() - Sets level to 'error' for error notifications
• level(string $level) - Sets custom level string

Sources: src/Messages/SimpleMessage.php58-85

Content Methods

Methods for building the message body:

• subject(string $subject) - Sets the email subject
• greeting(string $greeting) - Sets opening greeting text
• salutation(string $salutation) - Sets closing salutation text
• line(mixed $line) - Adds a single content line
• lines(iterable $lines) - Adds multiple content lines
• lineIf(bool $boolean, mixed $line) - Conditionally adds a line
• linesIf(bool $boolean, iterable $lines) - Conditionally adds multiple lines

Lines are automatically formatted by formatLine() which handles Htmlable objects, arrays, and multi-line strings.

Sources: src/Messages/SimpleMessage.php87-191

Action Button

The action button appears between intro and outro lines:

• action(string $text, string $url) - Configures the call-to-action button

When action() is called, subsequent line() calls add content to outroLines instead of introLines.

Sources: src/Messages/SimpleMessage.php194-202 src/Messages/SimpleMessage.php164-175

---

MailMessage Class

MailMessage extends SimpleMessage with email-specific features including view rendering, email headers, attachments, and delivery metadata.

View Rendering Options

MailMessage supports two rendering modes: custom views and Markdown templates.

Sources: src/Messages/MailMessage.php21-33 src/Messages/MailMessage.php93-145

Custom Views

Use custom blade/view templates for complete control over email rendering:

• view(array|string $view, array $data = []) - Sets custom view template
• text(string $textView, array $data = []) - Adds plain text version

The view parameter accepts either:

• A string path to a single HTML view
• An array with 'html' and 'text' keys for dual-format emails

Calling view() sets the markdown property to null.

Sources: src/Messages/MailMessage.php93-112

Markdown Templates

Use structured Markdown templates for standardized notification emails:

• markdown(string $view, array $data = []) - Sets Markdown template path
• template(string $template) - Alias for setting the markdown template
• theme(string $theme) - Sets the Markdown theme for styling

Default markdown template is 'notifications::email'. Calling markdown() sets the view property to null.

Sources: src/Messages/MailMessage.php117-145 src/Messages/MailMessage.php33

Rendering Process

Sources: src/Messages/MailMessage.php306-322

The render() method (implementing Renderable interface) produces HTML output:

1. If view property is set, uses the mailer's render() method
2. Otherwise, uses Markdown service with theme configuration
3. Data passed includes both viewData and all properties from toArray()

Sources: src/Messages/MailMessage.php16 src/Messages/MailMessage.php280-283 src/Messages/MailMessage.php306-322

---

Email Headers and Recipients

MailMessage provides methods for configuring standard email headers:

Sender Information

• from(string $address, ?string $name = null) - Sets the from address

Stored in the from array property as [$address, $name].

Sources: src/Messages/MailMessage.php43 src/Messages/MailMessage.php150-155

Reply-To Addresses

• replyTo(array|string $address, ?string $name = null) - Adds reply-to address(es)

Supports both single addresses and arrays of addresses. Multiple calls accumulate addresses in the replyTo array.

Sources: src/Messages/MailMessage.php48 src/Messages/MailMessage.php160-169

Carbon Copy Recipients

• cc(array|string $address, ?string $name = null) - Adds CC recipient(s)
• bcc(array|string $address, ?string $name = null) - Adds BCC recipient(s)

Both methods support single addresses or arrays. Addresses accumulate in the respective cc and bcc arrays.

Sources: src/Messages/MailMessage.php53-58 src/Messages/MailMessage.php174-197

Address Parsing

The methods replyTo(), cc(), and bcc() use helper methods to handle different address formats:

• arrayOfAddresses(mixed $address) - Detects if input is iterable or Arrayable
• parseAddresses(array $value) - Normalizes address arrays to [[address, name], ...] format

Sources: src/Messages/MailMessage.php288-301

---

Attachments

MailMessage supports three types of file attachments:

File Attachments

Sources: src/Messages/MailMessage.php202-215

• attach(Attachable|Attachment|string $file, array $options = []) - Attaches a file

  • Attachable objects are converted via toMailAttachment()
  • Attachment objects call attachTo($this)
  • String paths are stored with options in the attachments array

• attachMany(array $files) - Attaches multiple files at once

Sources: src/Messages/MailMessage.php63 src/Messages/MailMessage.php202-233

In-Memory Attachments

• attachData(string $data, string $name, array $options = []) - Attaches raw data as a file

Data attachments are stored separately in the rawAttachments array.

Sources: src/Messages/MailMessage.php68 src/Messages/MailMessage.php238-243

---

Email Metadata

MailMessage provides methods for setting transport-specific metadata:

Tags

• tag(string $value) - Adds a tag for categorization/tracking

Tags are accumulated in the tags array. Support depends on the underlying mail transport (e.g., Mailgun, Postmark).

Sources: src/Messages/MailMessage.php73 src/Messages/MailMessage.php248-253

Metadata

• metadata(string $key, string $value) - Adds key-value metadata

Metadata is stored in the metadata associative array. Like tags, support depends on the mail transport.

Sources: src/Messages/MailMessage.php78 src/Messages/MailMessage.php258-263

Priority

• priority(int $level) - Sets message priority (1=highest, 5=lowest)

Priority levels follow email standards where 1 is highest priority and 5 is lowest.

Sources: src/Messages/MailMessage.php83 src/Messages/MailMessage.php270-275

---

Advanced Features

Symfony Message Callbacks

The withSymfonyMessage() method allows direct manipulation of the underlying Symfony message object:

• withSymfonyMessage(callable $callback) - Registers callback for Symfony message

Callbacks are stored in the callbacks array and executed by the mail channel when building the actual email message. This provides access to lower-level Symfony mailer features.

Sources: src/Messages/MailMessage.php88 src/Messages/MailMessage.php327-332

Mailer Selection

Both SimpleMessage and MailMessage support specifying which named mailer configuration to use:

• mailer(string $mailer) - Sets the mailer name

This allows routing different notifications through different SMTP servers or transports.

Sources: src/Messages/SimpleMessage.php53-55 src/Messages/SimpleMessage.php207-212

Conditional Building

MailMessage uses the Conditionable trait, enabling conditional method chaining:

Sources: src/Messages/MailMessage.php18

---

Data Export

Both message classes provide array representations of their content:

SimpleMessage Data

toArray() returns structured content:

Sources: src/Messages/SimpleMessage.php217-230

MailMessage Data

data() merges toArray() with viewData for template rendering:

This combined data is passed to both custom views and Markdown templates during rendering.

Sources: src/Messages/MailMessage.php280-283

---

Property Summary

SimpleMessage Properties

Property	Type	Default	Description
level	string	'info'	Visual level indicator
subject	?string	null	Email subject line
greeting	?string	null	Opening greeting
salutation	?string	null	Closing salutation
introLines	array	[]	Lines before action
outroLines	array	[]	Lines after action
actionText	?string	null	Button label
actionUrl	?string	null	Button URL
mailer	?string	null	Named mailer

Sources: src/Messages/SimpleMessage.php12-55

MailMessage Properties

Property	Type	Default	Description
view	array|string|null	null	Custom view path(s)
viewData	array	[]	Data for view rendering
markdown	?string	'notifications::email'	Markdown template path
theme	?string	null	Markdown theme name
from	array	[]	From address [email, name]
replyTo	array	[]	Reply-to addresses
cc	array	[]	CC recipients
bcc	array	[]	BCC recipients
attachments	array	[]	File attachments
rawAttachments	array	[]	In-memory attachments
tags	array	[]	Transport tags
metadata	array	[]	Transport metadata
priority	int	-	Priority level (1-5)
callbacks	array	[]	Symfony message callbacks

Sources: src/Messages/MailMessage.php21-88