Messaging

Providing the from address

Messaging declares two required settings: the address mail is sent from, and the name it is sent as. A site provides them in index.php with Config::Provide, the same way it provides every other module's settings:

Config::Provide('Messaging', [
    'MESSAGING_EMAIL_FROM_EMAIL' => 'hello@example.com',
    'MESSAGING_EMAIL_FROM_NAME'  => 'My Site',
]);

Those are the from-address defaults for the site. The module declares them as required in its index file, so the security check stops a site that forgot to provide them.

Sending an email

Email is sent with MessagingEmail::Send. You pass the from address and name, the recipient address and name, a subject, a plain-text body, and an optional HTML body. It returns the id of the queued email:

MessagingEmail::Send(
    $fromEmail,
    $fromName,
    $toEmail,
    $toName,
    $subject,
    $text,
    $optionalHtml
);

Send does not talk to a mail server itself. It records the email and returns; the actual delivery happens on the email queue, so a slow provider never holds up the request that sent the mail. See Background work: queues and cron.

How other modules use it

Modules that need to send mail call Messaging rather than reaching for a mail library. The email authentication method is the clearest example: when a member asks for a login code or a forgotten-password code, the method builds the subject and body, reads the from name and address, and hands the message to Messaging:

// in MemberAuthMethodEmail, sending a login code
MessagingEmail::Send(
    $fromEmail,
    $fromName,
    $memberLogin,
    $memberLogin,
    $subject,
    $text,
    $html
);

The auth method knows nothing about mail providers or queues. It composes a message and sends it. Messaging owns everything past that point, which keeps mail delivery in one module for the whole site.

Next: The database layer.