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.
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:
send()- Sends the given email message.sendMultiple()- Sends many messages at once.
To create a simple message with a text body, use Yiisoft\Mailer\Message:
$message = new \Yiisoft\Mailer\Message(
from: '[email protected]',
to: '[email protected]',
subject: 'Message subject',
textBody: 'Plain text content'
);$message = new \Yiisoft\Mailer\Message(
from: '[email protected]',
to: '[email protected]',
subject: 'Message subject',
htmlBody: '<b>HTML content</b>'
);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: '[email protected]',
to: '[email protected]',
subject: 'Subject',
htmlBody: $content
);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: '[email protected]',
to: '[email protected]',
subject: 'Subject',
htmlBody: $content
);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>The Yiisoft\Mailer\MessageInterface provides several methods to customize your message:
withCharset()- Returns a new instance with the specified charset.withFrom()- Returns a new instance with the specified sender email address.withTo()- Returns a new instance with the specified recipient(s) email address.withReplyTo()- Returns a new instance with the specified reply-to address.withCc()- Returns a new instance with the specified Cc (extra copy receiver) addresses.withBcc()- Returns a new instance with the specified Bcc (hidden copy receiver) addresses.withSubject()- Returns a new instance with the specified message subject.withDate()- Returns a new instance with the specified date when the message was sent.withPriority()- Returns a new instance with the specified priority of this message.withReturnPath()- Returns a new instance with the specified return-path (the bounce address) of this message.withSender()- Returns a new instance with the specified actual sender email address.withHtmlBody()- Returns a new instance with the specified message HTML content.withTextBody()- Returns a new instance with the specified message plain text content.withAddedHeader()- Returns a new instance with the specified added custom header value.withHeader()- Returns a new instance with the specified custom header value.withHeaders()- Returns a new instance with the specified custom header values.
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.
The following getters are available to retrieve message data:
getCharset()- Returns the charset of this message.getFrom()- Returns the message sender email address.getTo()- Returns the message recipient(s) email address.getReplyTo()- Returns the reply-to address of this message.getCc()- Returns the Cc (extra copy receiver) addresses of this message.getBcc()- Returns the Bcc (hidden copy receiver) addresses of this message.getSubject()- Returns the message subject.getDate()- Returns the date when the message was sent, or null if it wasn't set.getPriority()- Returns the priority of this message.getReturnPath()- Returns the return-path (the bounce address) of this message.getSender()- Returns the message actual sender email address.getHtmlBody()- Returns the message HTML body.getTextBody()- Returns the message text body.getHeader()- Returns all values for the specified header.__toString()- Returns string representation of this message.
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'),
);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: '[email protected]',
to: '[email protected]',
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; ?>">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: '[email protected]',
to: '[email protected]',
subject: 'Subject',
htmlBody: $content
);
$mailer->send($message);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.
To create a custom mail solution, implement the Yiisoft\Mailer\MailerInterface and Yiisoft\Mailer\MessageInterface
interfaces.
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:
Yiisoft\Mailer\StubMailer- A simple mailer that stores messages in a local array.Yiisoft\Mailer\FileMailer- A mock mailer that saves email messages as files instead of sending them.Yiisoft\Mailer\NullMailer- A mailer that discards messages without sending or storing them.
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
];