docs

Various Yii 3.0 related documentation

View the Project on GitHub yiisoft/docs

Mailing

Yii simplifies the composition and sending of email messages using the yiisoft/mailer package. This package provides content composition functionality and a basic interface for sending emails. By default, the package includes a file mailer that writes email contents into a file instead of sending them. This is particularly useful during the initial stages of application development.

To send actual emails, you can use the Symfony Mailer implementation, which is used in the examples below.

Configuring the Mailer

The mailer service allows you to create a message instance, populate it with data, and send it. Typically, you obtain an instance from the DI container as Yiisoft\Mailer\MailerInterface.

You can also create an instance manually as follows:


use Yiisoft\Mailer\Symfony\Mailer;

/**
 * @var \Symfony\Component\Mailer\Transport\TransportInterface $transport
 */

$mailer = new \Yiisoft\Mailer\Symfony\Mailer(
    $transport,
);

The Yiisoft\Mailer\MailerInterface provides two main methods:

Creating a Message

Simple Text Message

To create a simple message with a text body, use Yiisoft\Mailer\Message:

$message = new \Yiisoft\Mailer\Message(
    from: 'from@domain.com',
    to: 'to@domain.com',
    subject: 'Message subject',
    textBody: 'Plain text content'
);

Simple HTML Message

$message = new \Yiisoft\Mailer\Message(
    from: 'from@domain.com',
    to: 'to@domain.com',
    subject: 'Message subject',
    htmlBody: '<b>HTML content</b>'
);

HTML Message from template

For this example we will use package rendering package view.

/**
 * @var \Yiisoft\View\View $view
 */

$content = $view->render('path/to/view.php', [
    'name' => 'name',
    'code' => 'code',
]);

$message = new \Yiisoft\Mailer\Message(
    from: 'from@domain.com',
    to: 'to@domain.com',
    subject: 'Subject',
    htmlBody: $content
);

Using Layouts

You can also pass parameters to layouts from you template message:

/**
 * @var \Yiisoft\View\View $view
 * @var array $layoutParameters
 */

$messageBody = $view->render('path/to/view.php', [
    'name' => 'name',
    'code' => 'code',
]);

$layoutParameters['content'] = $messageBody;

$content = $view->render('path/to/layout.php', $layoutParameters);

$message = new \Yiisoft\Mailer\Message(
    from: 'from@domain.com',
    to: 'to@domain.com',
    subject: 'Subject',
    htmlBody: $content
);

Layout Example

You can wrap the view rendering result in a layout, similar to how layouts work in web applications. This is useful for setting up shared content like CSS styles:

<?php
/* @var $content string Mail contents as view render result */
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>

<?= $content ?>

<footer style="margin-top: 5em">
-- <br>
Mailed by Yii
</footer>

</body>
</html>

Adding More Data

The Yiisoft\Mailer\MessageInterface provides several methods to customize your message:

These methods are immutable, meaning they return a new instance of the message with the updated data.

Note with prefix. It indicates that the method is immutable and returns a new instance of the class with the changed data.

Getters

The following getters are available to retrieve message data:

Attaching Files

You can attach files to your message using the withAttached() method:

use Yiisoft\Mailer\File;

// Attach a file from the local file system
$message = $message->withAttached(
    File::fromPath('/path/to/source/file.pdf'),
);

// Create an attachment on-the-fly
$message = $message->withAttached(
    File::fromContent('Attachment content', 'attach.txt', 'text/plain'),
);

Embedding Images

You can embed images into the message content using the withEmbedded() method. This is particularly useful when composing messages with views:

$logo = 'path/to/logo';
$htmlBody = $this->view->render(
    __DIR__ . 'template.php',
    [
        'content' => $content,
        'logoCid' => $logo->cid(),
    ],
);
return new \Yiisoft\Mailer\Message(
            from: 'from@domain.com',
            to: 'to@domain.com',
            subject: 'Message subject',
            htmlBody: $htmlBody,
            embeddings: $logo
        );

In your view or layout template, you can reference the embedded image using its CID:

<img src="<?= $logoCid; ?>">

Sending a Message

To send an email message:

/**
 * @var \Yiisoft\View\View $view
 */

$content = $view->render('path/to/view.php', [
    'name' => 'name',
    'code' => 'code',
]);

$message = new \Yiisoft\Mailer\Message(
    from: 'from@domain.com',
    to: 'to@domain.com',
    subject: 'Subject',
    htmlBody: $content
);

$mailer->send($message);

Sending Multiple Messages

You can send multiple messages at once:

$messages = [];

foreach ($users as $user) {
    $messages[] = (new \Yiisoft\Mailer\Message())
        // ...
        ->withTo($user->email);
}

$result = $mailer->sendMultiple($messages);

The sendMultiple() method returns a Yiisoft\Mailer\SendResults object containing arrays of successfully sent and failed messages.

Implementing Your Own Mail Driver

To create a custom mail solution, implement the Yiisoft\Mailer\MailerInterface and Yiisoft\Mailer\MessageInterface interfaces.

For Development

For local or test development, you can use simplified implementations of the mailer that do not actually send emails. These implementations are provided by the package:

To use one of these mailers, configure it in your development environment file Example: environments/local/di.php

return [
    Yiisoft\Mailer\MailerInterface::class => Yiisoft\Mailer\StubMailer::class, //or any other
];