Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Components
  4. The Mailer Component
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • Installation
  • Usage
  • Transport
  • High Availability
  • Load Balancing
  • Sending emails asynchronously
  • Learn More

The Mailer Component

Edit this page

Warning: You are browsing the documentation for Symfony 4.3, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

The Mailer Component

The Mailer component helps sending emails.

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

4.3

The Mailer component was introduced in Symfony 4.3 and it's still considered an experimental feature.

Installation

1
$ composer require symfony/mailer

Note

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

Usage

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

1
2
3
4
5
6
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport;

$transport = new EsmtpTransport('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:

Service Install with
Amazon SES composer require symfony/amazon-mailer
Gmail composer require symfony/google-mailer
MailChimp composer require symfony/mailchimp-mailer
Mailgun composer require symfony/mailgun-mailer
Postmark composer require symfony/postmark-mailer
SendGrid composer require symfony/sendgrid-mailer

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

1
$ composer require symfony/google-mailer

Then, use the SMTP Gmail transport:

1
2
3
4
5
6
use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport;
use Symfony\Component\Mailer\Mailer;

$transport = new GmailTransport('user', 'pass');
$mailer = new Mailer($transport);
$mailer->send($email);

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

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

1
2
3
use Symfony\Component\Mailer\Transport;

$transport = Transport::fromDsn($dsn);

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

Provider SMTP HTTP API
Amazon SES smtp://ACCESS_KEY:SECRET_KEY@ses http://ACCESS_KEY:SECRET_KEY@ses api://ACCESS_KEY:SECRET_KEY@ses
Google Gmail smtp://USERNAME:PASSWORD@gmail n/a n/a
Mailchimp Mandrill smtp://USERNAME:PASSWORD@mandrill http://KEY@mandrill api://KEY@mandrill
Mailgun smtp://USERNAME:PASSWORD@mailgun http://KEY:DOMAIN@mailgun api://KEY:DOMAIN@mailgun
Postmark smtp://ID:ID@postmark n/a api://KEY@postmark
Sendgrid smtp://apikey:KEY@sendgrid n/a api://KEY@sendgrid

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:

1
$dsn = 'api://id@postmark || smtp://key@sendgrid';

The mailer will start using the first transport. If the sending fails, the mailer won't retry it with the other transports, but it will switch to the next transport 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:

1
$dsn = 'api://id@postmark && smtp://key@sendgrid'

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

Sending emails asynchronously

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

1
$ composer require symfony/messenger

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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('sender@example.com'),
    [
        new Address('recipient@example.com'),
    ]
));

Learn More

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

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:
Take the exam at home

Take the exam at home

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

Avatar of Hoffmann András, a Symfony contributor

Thanks Hoffmann András for being a Symfony contributor

1 commit • 16 lines changed

View all contributors that help us make Symfony

Become a Symfony contributor

Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

Learn how to contribute

Symfony™ is a trademark of Symfony SAS. All rights reserved.

  • What is Symfony?
    • Symfony at a Glance
    • Symfony Components
    • Case Studies
    • Symfony Releases
    • Security Policy
    • Logo & Screenshots
    • Trademark & Licenses
    • symfony1 Legacy
  • Learn Symfony
    • Symfony Docs
    • Symfony Book
    • Reference
    • Bundles
    • Best Practices
    • Training
    • eLearning Platform
    • Certification
  • Screencasts
    • Learn Symfony
    • Learn PHP
    • Learn JavaScript
    • Learn Drupal
    • Learn RESTful APIs
  • Community
    • SymfonyConnect
    • Support
    • How to be Involved
    • Code of Conduct
    • Events & Meetups
    • Projects using Symfony
    • Downloads Stats
    • Contributors
    • Backers
  • Blog
    • Events & Meetups
    • A week of symfony
    • Case studies
    • Cloud
    • Community
    • Conferences
    • Diversity
    • Documentation
    • Living on the edge
    • Releases
    • Security Advisories
    • SymfonyInsight
    • Twig
    • SensioLabs
  • Services
    • SensioLabs services
    • Train developers
    • Manage your project quality
    • Improve your project performance
    • Host Symfony projects
    Deployed on
Follow Symfony
Search by Algolia