📧 Mail — Sending Emails in PageBlocks

The Mail class is designed for composing and sending emails using the standard modMail service in MODX. In PageBlocks, it simplifies email handling and supports Fenom templates for content generation.

📌 Purpose

Mail wraps the modMail functionality and allows configuring all email parameters via method chaining. The email body can be set directly or generated via a Fenom template.

⚙️ Default Values

When creating a Mail object, some parameters are automatically pulled from MODX system settings:

Property	Default Value
from	emailsender from MODX system settings
fromName	site_name from MODX system settings
sender	emailsender from MODX system settings
isHtml	true — emails are sent in HTML format

Example:

$mail = Mail::to('user@example.com');  
// $mail->from will be equal to $modx->getOption('emailsender')

✅ Quick Example

use Boshnik\PageBlocks\Support\Mail;  

Mail::to('recipient@example.com')  
    ->subject('Welcome')  
    ->message('<p>Thank you for registering!</p>')  
    ->send();

🗂️ Class Methods

➡️ Mail::to(string $email): Mail

Sets the recipient's email address.

➡️ subject(string $text): Mail

Sets the email subject.

➡️ message(string $html): Mail

Sets the email body directly (HTML or plain text).

➡️ view(string $tpl, array $data = []): Mail

Renders the email using a Fenom template and provided data.

Example:

Mail::to('user@example.com')  
    ->subject('Your Order')  
    ->view('file:emails/order', ['order' => $order])  
    ->send();

➡️ attach($file): Mail

Attaches a file to the email.

->attach([  
    'url' => MODX_BASE_PATH . 'assets/docs/contract.pdf',  
    'name' => 'Contract.pdf'  
]);

➡️ replyTo(string $email): Mail

Sets the reply-to address.

➡️ cc(string $email): Mail

Adds a CC recipient.

➡️ bcc(string $email): Mail

Adds a BCC recipient.

➡️ from(string $email, string $name = ''): Mail

Changes the sender's email and name.

➡️ sender(string $email): Mail

Changes the MAIL_SENDER.

➡️ setHTML(bool $html = true): Mail

Specifies whether to send the email in HTML or plain text format.

➡️ send(string $to = '', string $subject = '', string $message = ''): bool

Sends the email.
Returns true on success and logs an error in MODX if sending fails.

🗂️ Example: Fenom + Attachment + CC/BCC

Mail::to('user@example.com')  
    ->subject('Your Order Has Been Accepted')  
    ->view('emails/order', ['order' => $order])  
    ->attach([  
        'url' => MODX_BASE_PATH . 'assets/invoices/invoice.pdf',  
        'name' => 'Invoice.pdf'  
    ])  
    ->cc('manager@example.com')  
    ->bcc('admin@example.com')  
    ->send();

📝 Error Logging

If an email fails to send, an error will be logged in the MODX system log (core/cache/logs/error.log) with the ERROR level and the [Mail] prefix.

📚 Summary

• Mail — a convenient class for sending emails with Fenom templates and attachments.
• Uses MODX settings for default from, fromName, and sender values.
• Allows easy configuration of recipients, copies, and sending format.