The Mailer Component

The Mailer component helps sending emails.

If you're using the Symfony Framework, read theSymfony Framework Mailer documentation.

New in version 4.3: The Mailer component was introduced in Symfony 4.3 and it's stillconsidered an experimental feature.

Installation

$ composer require symfony/mailer

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Usage

The Mailer component has two main classes: a Transport and the Mailer itself:

use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport;
 
$transport = new SmtpTransport('localhost');
$mailer = new Mailer($transport);
$mailer->send($email);

The $email object is created via the Mime component.

Transport

The only transport that comes pre-installed is SMTP.

Below is the list of other popular providers with built-in support:

For example, suppose you want to use Google's Gmail SMTP server. First, installit:

$ composer require symfony/google-mailer

Then, use the SMTP Gmail transport:

use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport;
 
$transport = new GmailTransport('user', 'pass');
$mailer = new Mailer($transport);
$mailer->send($email);

Each provider provides up to 3 transports: standard SMTP, HTTP (it uses theprovider's API but the body is created by the mailer component), API (it usesthe full API of the provider with no control over the body creation — featuresmight be limited as well).

The mailer component provides a convenient way to create a transport from aDSN:

use Symfony\Component\Mailer\Transport;
 
$transport = Transport::fromDsn($dsn);

Where $dsn depends on the provider you want to use. For plain SMTP, usesmtp://user:pass@example.com or smtp://sendmail to use the sendmailbinary. For third-party providers, refers to the following table:

High Availability

Symfony's mailer supports high availability via a technique called "failover"to ensure that emails are sent even if one mailer server fails .

A failover transport is configured with two or more transports joined by the|| operator:

$dsn = 'api://[email protected] || smtp://[email protected]';

The mailer will start using the first transport. If the sending fails, themailer won't retry it with the other transports, but it will switch to the nexttransport automatically for the following deliveries.

Load Balancing

Symfony's mailer supports load balancing) via a technique called "round-robin"to distribute the mailing workload across multiple transports .

A round-robin transport is configured with two or more transports joined by the&& operator:

$dsn = 'api://[email protected] && smtp://[email protected]'

The mailer will start using the first transport and if it fails, it will retrythe same delivery with the next transports until one of them succeeds (or untilall of them fail).

Sending emails asynchronously

If you want to send emails asynchronously, install the Messenger component.

$ composer require symfony/messenger

Then, instantiate and pass a MessageBus as a second argument to Mailer:

use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Messenger\MessageHandler;
use Symfony\Component\Mailer\Messenger\SendEmailMessage;
use Symfony\Component\Mailer\SmtpEnvelope;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Messenger\Handler\HandlersLocator;
use Symfony\Component\Messenger\MessageBus;
use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;
use Symfony\Component\Mime\Address;
 
$dsn = 'change-dsn-accordingly';
 
$transport = Transport::fromDsn($dsn);
$handler = new MessageHandler($transport);
 
$bus = new MessageBus([
    new HandleMessageMiddleware(new HandlersLocator([
        SendEmailMessage::class => [$handler],
    ])),
]);
 
$mailer = new Mailer($transport, $bus);
$mailer->send($email);
 
// you can pass an optional Envelope
$mailer->send($email, new SmtpEnvelope(
    new Address('[email protected]'),
    [
        new Address('[email protected]'),
    ]
));

Learn More

To learn more about how to use the mailer component, refer to theSymfony Framework Mailer documentation.