Usage Guide

Building Emails with Mailable

The Mailable class provides a fluent interface for constructing emails.

Setting Recipients

use WPZylos\Framework\Mail\Mailable;

$mail = new Mailable();

// Single recipient
$mail->to('[email protected]');

// Multiple recipients
$mail->to(['[email protected]', '[email protected]']);

// Chain multiple calls
$mail->to('[email protected]')
     ->to('[email protected]');

// CC and BCC
$mail->cc('[email protected]')
     ->bcc('[email protected]');

Setting Sender Information

// Custom from address
$mail->from('[email protected]', 'My Plugin');

// Reply-to address
$mail->replyTo('[email protected]');

Setting Subject

$mail->subject('Your Order Has Been Shipped');

Building the Email Body

There are four ways to set the email body, in priority order:

1. Raw HTML

$mail->html('<h1>Welcome!</h1><p>Thank you for signing up.</p>');

2. Plain Text

$mail->text('Welcome! Thank you for signing up.');

3. PHP View Template

// Render a PHP template file
$mail->templatePath('/path/to/templates')
     ->view('welcome', ['name' => 'John', 'plan' => 'Pro']);

The template file (/path/to/templates/welcome.php) receives the data as extracted variables:

<!-- welcome.php -->
<h1>Welcome, <?= htmlspecialchars($name) ?>!</h1>
<p>You are now on the <?= htmlspecialchars($plan) ?> plan.</p>

4. Component Parts (Greeting + Lines + Action)

$mail->greeting('Hello John!')
     ->line('Your order #1234 has been shipped.')
     ->line('Expected delivery: 3-5 business days.')
     ->action('Track Order', 'https://example.com/track/1234')
     ->line('Thank you for your purchase!');

This automatically wraps content in a responsive HTML email layout.

Adding Attachments

$mail->attach('/path/to/invoice.pdf')
     ->attach('/path/to/receipt.pdf');

Custom Headers

$mail->header('X-Priority', '1')
     ->header('X-Campaign-ID', 'welcome-series');

Sending

// Returns true on success, false on failure
$result = $mail->send();

Inspecting Without Sending

$built = $mail->build();

// $built['to']          — array of recipient addresses
// $built['subject']     — subject line
// $built['message']     — rendered body (HTML or text)
// $built['headers']     — array of header strings
// $built['attachments'] — array of file paths

Using MailManager

The MailManager provides a centralized interface with preconfigured defaults.

Basic Usage

use WPZylos\Framework\Mail\MailManager;

$mailManager = $app->make(MailManager::class);

$mailManager->to('[email protected]')
    ->subject('Welcome!')
    ->greeting('Hello!')
    ->line('Welcome to our platform.')
    ->send();

Configuring Defaults

// Set default from address
$mailManager->setFrom('[email protected]', 'My Plugin');

// All subsequent emails use this from address
$mailManager->to('[email protected]')
    ->subject('Notification')
    ->line('You have a new message.')
    ->send();
// From: My Plugin <[email protected]>

Default Template Path

When MailManager creates a Mailable, it automatically sets the template path to your plugin's resources/mail directory (if it exists). This means you can use view() with just the template name:

$mailManager->to('[email protected]')
    ->subject('Invoice')
    ->view('invoice', ['order' => $order])
    ->send();
// Looks for: {plugin_path}/resources/mail/invoice.php

Sending Pre-Built Mailables

$mailable = new Mailable();
$mailable->to('[email protected]')
    ->subject('Custom Email')
    ->html('<p>Custom content</p>');

$mailManager->send($mailable);

Creating Mailables with Defaults

$mailable = $mailManager->createMailable();
// Has from address and template path pre-configured

$mailable->to('[email protected]')
    ->subject('Pre-configured')
    ->line('This email has defaults applied.')
    ->send();