1. INTRODUCTION

Kristal Framework’s Mailer class sends HTML emails using your provider’s SMTP service. Create an email template, fill in its values and call send().

Email templates are located in App/templates/emails/.

2. CONFIGURING SMTP

Edit the mail settings in config/config.php with the details from your email provider:

define("MAILER_HOST", "smtp.example.com");
define("MAILER_EMAIL", "notifications@example.com");
define("MAILER_PASSWORD", "replace-with-your-smtp-password");
define("MAILER_NAME", "My Website");
define("MAILER_PROTOCOL", "tls");
define("MAILER_PORT", 587);

MAILER_EMAIL is both the sending address and SMTP username. MAILER_NAME is the name recipients see.

Use the protocol and port your provider gives you. Common combinations are tls with port 587, or ssl with port 465.

3. CREATING AN EMAIL TEMPLATE

Create App/templates/emails/welcome.php:

<!doctype html>
<html lang="en">
    <body>
        <h1>Welcome, {{ name }}!</h1>
        <p>A message from {{ site_name }}.</p>
        <p><a href="{{ website_url }}">Visit the website</a></p>
    </body>
</html>

Values such as {{ name }} are placeholders. Keep one space on each side of the name, as shown. We’ll fill them when sending the email.

Placeholder values are escaped automatically. Pass ordinary text, and keep the email’s HTML in the template.

4. SENDING AN EMAIL

Add the Mailer import near the top of your PHP file. Then create the mailer and send your message from a route or form handler:

use Backend\Core\Mailer;

$mailer = new Mailer();

$sent = $mailer->send(
    "alex@example.com",
    "Welcome to My Website",
    "welcome",
    [
        "name" => "Alex",
        "site_name" => "My Website",
        "website_url" => URL_BASE,
    ]
);

if (!$sent)
{
    debuglog("The welcome email could not be sent.", "warning");
}

The four arguments are:

1. The recipient’s address.
2. The email subject.
3. The template name.
4. The values to place in the template.

Both welcome and welcome.php select the template above. Use your own trusted website URLs for links in the message.

send() returns true when the mail service accepts the send operation. If sending fails or the template is missing, it returns false and records details when logging is enabled. A successful send does not guarantee that the message reaches the inbox.

5. RECIPIENTS AND REPLY-TO

To send the same message to several people, pass an array of addresses:

$sent = $mailer->send(
    ["alex@example.com", "sam@example.com"],
    "Welcome to My Website",
    "welcome",
    [
        "name" => "everyone",
        "site_name" => "My Website",
        "website_url" => URL_BASE,
    ]
);

All recipients can see these addresses in the To field. Send separate messages if the addresses should stay private.

To choose where replies go, call this before send():

$mailer->setReplyToEmail("support@example.com", "Website Support");

Recipients and reply-to addresses are cleared after each send. Set the reply-to again before sending another message that needs it.

6. TROUBLESHOOTING

If an email isn’t sent, check the template filename and your SMTP host, credentials, protocol and port. Make sure the server can connect to your email provider.

Enable ENABLE_DEBUG_LOG and use a writable DEBUG_LOG_PATH to see error details.

If a placeholder is still visible in the email, check that its name and spaces match the example. Put HTML in the template itself; HTML passed as a placeholder value will display as text.