Emails

• MailSender Class
• Method Parameters
• Usage Example
• Sender Identity
• Unreachable Servers
• Delivery & Tracking Hooks
• Exception Reports

MailSender Class

The MailSender class in Sukarix is used to send emails with a predefined template. The primary method for sending emails is send(), which has the following signature:

send($template, $vars, $to, $title, $subject): bool

Method Parameters

• $template: The name of the email template, which must be located in the /mail folder.
• $vars: An array of variables to be used within the template.
• $to: The recipient’s email address.
• $title: The title of the email.
• $subject: The subject line of the email.

Usage Example

Here’s how you might use the send() method to send an email:

/**
 * @var MailSender $mailSender
 */
$mailSender = Injector::instance()->get('mailer');
$template = 'welcome';
$vars = ['name' => 'John Doe', 'link' => 'https://example.com'];
$to = 'johndoe@example.com';
$title = 'Welcome to Our Service';
$subject = 'Getting Started with Our Service';

$mailSender->send($template, $vars, $to, $title, $subject);

This example sends a welcome email using the welcome template, passing in the recipient’s name and a link to be used within the email body.

Sender Identity

Three settings decide who the mail comes from, and they are deliberately separate:

A relay such as Postal authenticates as one identity and sends as another, so the account is not the address. The sender name is put on the message itself; without it the mail arrives showing a bare address.

[mailer]
smtp.host = postal.example.org
smtp.port = 587
smtp.user = rooms-app-7f3c
smtp.pw   = …
from_mail = notifications@rooms.example.org
from_name = Example Rooms

Unreachable Servers

The SMTP transport aborts the whole request when the server cannot be reached — not an exception the application can catch, the request simply dies. MailSender therefore checks that the server accepts a connection before handing the message over, logs the failure and returns false, leaving the caller to report it:

if (!$mailSender->send($template, $vars, $to, $title, $subject)) {
    // The message was not sent; the reason is in the log.
}

The wait is two seconds by default and is configurable with mailer.smtp.timeout.

Delivery & Tracking Hooks

MailSender sits on ikkez/f3-mailer, which calls back into the application on three events — wired in smtp.ini:

[mailer]
on.failure = \Sukarix\Mail\Track::logError
on.ping    = \Sukarix\Mail\Track::traceMail
on.jump    = \Sukarix\Mail\Track::traceClick

Sukarix\Mail\Track is the default implementation, logging all three to the mail channel. An application that wants its own behaviour points these at its own class instead — the callback just needs the same three static methods.

• on.failure fires when the SMTP transport reports a failed send; the callback receives the Mailer instance and the SMTP transcript.
• on.ping fires when a tracking pixel embedded in a sent mail is loaded; the callback receives the tracking hash.
• on.jump fires when a tracked link in a sent mail is followed, just before the browser is redirected to the real target; the callback receives the target URL.

fatfree-core’s SMTP client echoes the AUTH LOGIN/AUTH PLAIN exchange into the transcript as bare base64 lines — the account’s username and password, not encrypted, only encoded. Track::logError() strips those lines before writing the transcript to the log, so a relay account’s credentials never end up there even when a send fails.

Exception Reports

When error.channel is set to email, an uncaught exception is reported to debug.email. Repeats of the same exception are snoozed for a day so a failing deployment does not flood the inbox. The report is sent under mailer.debugger_name, which defaults to Application Debugger:

[mailer]
debugger_name = Example Rooms Debugger

Naming it after the application makes the report recognisable in an inbox that receives several.