Mail

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that the material is changing frequently and may be incomplete or inaccurate, and links may point back to older versions.

• On this Page

  • System Messages
  • Other Mailables
  • Mail Events

Mailer adapters are no longer necessary, as drivers are configured directly via Laravel (opens new window), in config/mailer.php.

System Messages

Craft’s System Messages utility is still used to manage built-in and plugin-provided email messages.

Your plugin can register system messages by implementing the getSystemMessages() method:

use CraftCms\Cms\SystemMessage\Data\SystemMessage;

public function getSystemMessages()
{
    return [
        'report_finished' => fn () => new SystemMessage(
            key: 'report_finished',
            heading: 'When a report is finished generating',
            subject: 'Here is your {report.template.name} report',
            body: "Hi, {report.creator.fullName}!\n\nA {report.template.name} just finished running. To download it, ...",
        ),
    ];
}

This method is invoked as your plugin is booted, so each value in the returned array must be a closure, under the same key the SystemMessage will produce, later.

To send a system message, pass the “mailable” to Laravel’s Mail facade:

use CraftCms\Cms\SystemMessage\SystemMessages;
use Illuminate\Support\Facades\Mail;

$message = app(SystemMessages::class)->mailable('report_finished', $report->creator, [
    'report' => $report,
]);

Mail::send($message);

Other Mailables

A system messages is just one implementation of Laravel’s Mailable, with the notable limitation of requiring an existing Craft user. For all other email, extend our CraftCms\Cms\Email\Mailables\CraftMailable class:

namespace MyOrg\Activity\Notifications;

use CraftCms\Cms\Email\Mailables\CraftMailable;

class ReportFinished extends CraftMailable
{
    public int $reportId;
    public string $summary = '';

    // ...
}

This gives your mailables a siteId property, which helps Craft pick up site-specific mailer overrides before sending:

$message = new ReportFinished($report);
$message->setTo($report->notifyEmail);
$message->siteId = $report->getTemplate()->siteId;

// Send after resolving mailer overrides for `siteId`:
$message->send();

Mail Events

Register a listener for Illuminate\Mail\Events\MessageSending to monitor outgoing emails, and return false to suppress them.