Sending Emails with Mailer
Warning: You are browsing the documentation for Symfony 4.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
4.3
The Mailer component was introduced in Symfony 4.3 and replaces Swift Mailer.
Installation
Symfony's Mailer & Mime components form a powerful system for creating and sending emails - complete with support for multipart messages, Twig integration, CSS inlining, file attachments and a lot more. Get them installed with:
1
$ composer require symfony/mailer
Transport Setup
Emails are delivered via a "transport". Out of the box, you can deliver emails
over SMTP by configuring the DSN in your .env
file (the user
,
pass
and port
parameters are optional):
1 2
# .env
MAILER_DSN=smtp://user:pass@smtp.example.com:port
1 2 3 4
# config/packages/mailer.yaml
framework:
mailer:
dsn: '%env(MAILER_DSN)%'
1 2 3 4 5 6 7 8 9 10 11 12
<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:mailer dsn="%env(MAILER_DSN)%"/>
</framework:config>
</container>
1 2 3 4 5 6 7 8 9
// config/packages/mailer.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
return static function (ContainerConfigurator $containerConfigurator): void {
$containerConfigurator->extension('framework', [
'mailer' => [
'dsn' => '%env(MAILER_DSN)%',
],
]);
};
Caution
If the username, password or host contain any character considered special in a
URI (such as +
, @
, $
, #
, /
, :
, *
, !
), you must
encode them. See RFC 3986 for the full list of reserved characters or use the
urlencode function to encode them.
Caution
If you are migrating from Swiftmailer (and the Swiftmailer bundle), be warned that the DSN format is different.
Using Built-in Transports
DSN protocol | Example | Description |
---|---|---|
smtp | smtp://user:pass@smtp.example.com:25 |
Mailer uses an SMTP server to send emails |
sendmail | sendmail://default |
Mailer uses the local sendmail binary to send emails |
Using a 3rd Party Transport
Instead of using your own SMTP server, you can send emails via a 3rd party provider. Mailer supports several - install whichever you want:
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 |
Each library includes a Symfony Flex recipe that will add
a configuration example to your .env
file. For example, suppose you want to
use SendGrid. First, install it:
1
$ composer require symfony/sendgrid-mailer
You'll now have a new line in your .env
file that you can uncomment:
1 2
# .env
MAILER_DSN=sendgrid://KEY@default
The MAILER_DSN
isn't a real address: it's a convenient format that
offloads most of the configuration work to mailer. The sendgrid
scheme
activates the SendGrid provider that you just installed, which knows all about
how to deliver messages via SendGrid. The only part you need to change is the
KEY
placeholder.
Each provider has different environment variables that the Mailer uses to
configure the actual protocol, address and authentication for delivery. Some
also have options that can be configured with query parameters at the end of the
MAILER_DSN
- like ?region=
for Amazon SES or Mailgun. Some providers support
sending via http
, api
or smtp
. Symfony chooses the best available
transport, but you can force to use one:
1 2 3
# .env
# force to use SMTP instead of HTTP (which is the default)
MAILER_DSN=sendgrid+smtp://$SENDGRID_KEY@default
This table shows the full list of available DSN formats for each third party provider:
Provider | SMTP | HTTP | API |
---|---|---|---|
Amazon SES | ses+smtp://USERNAME:PASSWORD@default | ses+https://ACCESS_KEY:SECRET_KEY@default | ses+api://ACCESS_KEY:SECRET_KEY@default |
Google Gmail | gmail+smtp://USERNAME:PASSWORD@default | n/a | n/a |
Mailchimp Mandrill | mandrill+smtp://USERNAME:PASSWORD@default | mandrill+https://KEY@default | mandrill+api://KEY@default |
Mailgun | mailgun+smtp://USERNAME:PASSWORD@default | mailgun+https://KEY:DOMAIN@default | mailgun+api://KEY:DOMAIN@default |
Postmark | postmark+smtp://ID@default | n/a | postmark+api://KEY@default |
Sendgrid | sendgrid+smtp://KEY@default | n/a | sendgrid+api://KEY@default |
Caution
If your credentials contain special characters, you must URL-encode them.
For example, the DSN ses+smtp://ABC1234:abc+12/345@default
should be
configured as ses+smtp://ABC1234:abc%2B12%2F345@default
Caution
Symfony 4.4 only supports Amazon SES signature version 3 which has been
deprecated. You need to use symfony/amazon-mailer
5.1 or newer.
Tip
If you want to override the default host for a provider (to debug an issue using
a service like requestbin.com
), change default
by your host:
1 2
# .env
MAILER_DSN=mailgun+https://KEY:DOMAIN@requestbin.com
Note that the protocol is always HTTPs and cannot be changed.
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 and the
failover
keyword:
1
MAILER_DSN="failover(postmark+api://ID@default sendgrid+smtp://KEY@default)"
The failover-transport starts 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).
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 and the
roundrobin
keyword:
1
MAILER_DSN="roundrobin(postmark+api://ID@default sendgrid+smtp://KEY@default)"
The round-robin transport starts with a randomly selected transport and then switches to the next available transport for each subsequent email.
As with the failover transport, round-robin retries deliveries until a transport succeeds (or all fail). In contrast to the failover transport, it spreads the load across all its transports.
Creating & Sending Messages
To send an email, get a Mailer instance by type-hinting MailerInterface and create an Email object:
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 32
// src/Controller/MailerController.php
namespace App\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Mime\Email;
use Symfony\Component\Routing\Annotation\Route;
class MailerController extends AbstractController
{
/**
* @Route("/email")
*/
public function sendEmail(MailerInterface $mailer): Response
{
$email = (new Email())
->from('hello@example.com')
->to('you@example.com')
//->cc('cc@example.com')
//->bcc('bcc@example.com')
//->replyTo('fabien@example.com')
//->priority(Email::PRIORITY_HIGH)
->subject('Time for Symfony Mailer!')
->text('Sending emails is fun again!')
->html('<p>See Twig integration for better HTML integration!</p>');
$mailer->send($email);
// ...
}
}
That's it! The message will be sent via the transport you configured.
Email Addresses
All the methods that require email addresses (from()
, to()
, etc.) accept
both strings or address objects:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
// ...
use Symfony\Component\Mime\Address;
$email = (new Email())
// email address as a simple string
->from('fabien@example.com')
// email address as an object
->from(new Address('fabien@example.com'))
// defining the email address and name as an object
// (email clients will display the name)
->from(new Address('fabien@example.com', 'Fabien'))
// defining the email address and name as a string
// (the format must match: 'Name <email@example.com>')
->from(Address::fromString('Fabien Potencier <fabien@example.com>'))
// ...
;
Tip
Instead of calling ->from()
every time you create a new email, you can
create an event subscriber and listen to the
MessageEvent event to set the
same From
email to all messages.
Use addTo()
, addCc()
, or addBcc()
methods to add more addresses:
1 2 3 4 5 6 7 8
$email = (new Email())
->to('foo@example.com')
->addTo('bar@example.com')
->cc('cc@example.com')
->addCc('cc2@example.com')
// ...
;
Alternatively, you can pass multiple addresses to each method:
1 2 3 4 5 6 7 8
$toAddresses = ['foo@example.com', new Address('bar@example.com')];
$email = (new Email())
->to(...$toAddresses)
->cc('cc1@example.com', 'cc2@example.com')
// ...
;
Message Headers
Messages include a number of header fields to describe their contents. Symfony sets all the required headers automatically, but you can set your own headers too. There are different types of headers (Id header, Mailbox header, Date header, etc.) but most of the times you'll set text headers:
1 2 3 4 5 6 7 8 9 10 11 12
$email = (new Email())
->getHeaders()
// this non-standard header tells compliant autoresponders ("email holiday mode") to not
// reply to this message because it's an automated email
->addTextHeader('X-Auto-Response-Suppress', 'OOF, DR, RN, NRN, AutoReply')
// use an array if you want to add a header with multiple values
// (for example in the "References" or "In-Reply-To" header)
->addIdHeader('References', ['123@example.com', '456@example.com'])
// ...
;
Message Contents
The text and HTML contents of the email messages can be strings (usually the result of rendering some template) or PHP resources:
1 2 3 4 5 6 7 8 9 10
$email = (new Email())
// ...
// simple contents defined as a string
->text('Lorem ipsum...')
->html('<p>Lorem ipsum...</p>')
// attach a file stream
->text(fopen('/path/to/emails/user_signup.txt', 'r'))
->html(fopen('/path/to/emails/user_signup.html', 'r'))
;
Tip
You can also use Twig templates to render the HTML and text contents. Read the Twig: HTML & CSS section later in this article to learn more.
File Attachments
Use the attachFromPath()
method to attach files that exist on your file system:
1 2 3 4 5 6 7 8
$email = (new Email())
// ...
->attachFromPath('/path/to/documents/terms-of-use.pdf')
// optionally you can tell email clients to display a custom name for the file
->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy')
// optionally you can provide an explicit MIME type (otherwise it's guessed)
->attachFromPath('/path/to/documents/contract.doc', 'Contract', 'application/msword')
;
Alternatively you can use the attach()
method to attach contents from a stream:
1 2 3 4
$email = (new Email())
// ...
->attach(fopen('/path/to/documents/contract.doc', 'r'))
;
Embedding Images
If you want to display images inside your email, you must embed them instead of adding them as attachments. When using Twig to render the email contents, as explained later in this article, the images are embedded automatically. Otherwise, you need to embed them manually.
First, use the embed()
or embedFromPath()
method to add an image from a
file or stream:
1 2 3 4 5 6 7
$email = (new Email())
// ...
// get the image contents from a PHP resource
->embed(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png')
// get the image contents from an existing file
->embedFromPath('/path/to/images/signature.gif', 'footer-signature', 'image/gif')
;
The second optional argument of both methods is the image name ("Content-ID" in the MIME standard). Its value is an arbitrary string used later to reference the images inside the HTML contents:
1 2 3 4 5 6 7 8
$email = (new Email())
// ...
->embed(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png')
->embedFromPath('/path/to/images/signature.gif', 'footer-signature', 'image/gif')
// reference images using the syntax 'cid:' + "image embed name"
->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...')
;
Handling Sending Failures
Symfony Mailer considers that sending was successful when your transport (SMTP server or third-party provider) accepts the mail for further delivery. The message can later be lost or not delivered because of some problem in your provider, but that's out of reach for your Symfony application.
If there's an error when handing over the email to your transport, Symfony throws a TransportExceptionInterface. Catch that exception to recover from the error or to display some message:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Mailer\Exception\TransportExceptionInterface;
$email = new Email();
// ...
try {
$mailer->send($email);
} catch (TransportExceptionInterface $e) {
// some error prevented the email sending; display an
// error message or try to resend the message
}
Debugging Emails
The SentMessage object returned by the
send()
method of the TransportInterface
provides access to the original message (getOriginalMessage()
) and to some
debug information (getDebug()
) such as the HTTP calls done by the HTTP
transports, which is useful to debug errors.
Note
Some mailer providers change the Message-Id
when sending the email. The
getMessageId()
method from SentMessage
always returns the definitive
ID of the message (being the original random ID generated by Symfony or the
new ID generated by the mailer provider).
4.4
The getMessageId()
method was introduced in Symfony 4.4.
The exceptions related to mailer transports (those which implement
TransportException) also provide
this debug information via the getDebug()
method.
4.4
The getDebug()
methods were introduced in Symfony 4.4.
Twig: HTML & CSS
The Mime component integrates with the Twig template engine to provide advanced features such as CSS style inlining and support for HTML/CSS frameworks to create complex HTML email messages. First, make sure Twig is installed:
1 2 3 4
$ composer require symfony/twig-bundle
# or if you're using the component in a non-Symfony app:
# composer require symfony/twig-bridge
HTML Content
To define the contents of your email with Twig, use the TemplatedEmail class. This class extends the normal Email class but adds some new methods for Twig templates:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
use Symfony\Bridge\Twig\Mime\TemplatedEmail;
$email = (new TemplatedEmail())
->from('fabien@example.com')
->to(new Address('ryan@example.com'))
->subject('Thanks for signing up!')
// path of the Twig template to render
->htmlTemplate('emails/signup.html.twig')
// pass variables (name => value) to the template
->context([
'expiration_date' => new \DateTime('+7 days'),
'username' => 'foo',
])
;
Then, create the template:
1 2 3 4 5 6 7 8 9 10 11 12
{# templates/emails/signup.html.twig #}
<h1>Welcome {{ email.toName }}!</h1>
<p>
You signed up as {{ username }} the following email:
</p>
<p><code>{{ email.to[0].address }}</code></p>
<p>
<a href="#">Click here to activate your account</a>
(this link is valid until {{ expiration_date|date('F jS') }})
</p>
The Twig template has access to any of the parameters passed in the context()
method of the TemplatedEmail
class and also to a special variable called
email
, which is an instance of
WrappedTemplatedEmail.
Text Content
When the text content of a TemplatedEmail
is not explicitly defined, mailer
will generate it automatically by converting the HTML contents into text. If you
have league/html-to-markdown installed in your application,
it uses that to turn HTML into Markdown (so the text email has some visual appeal).
Otherwise, it applies the strip_tags PHP function to the original
HTML contents.
If you want to define the text content yourself, use the text()
method
explained in the previous sections or the textTemplate()
method provided by
the TemplatedEmail
class:
1 2 3 4 5 6 7 8 9
+ use Symfony\Bridge\Twig\Mime\TemplatedEmail;
$email = (new TemplatedEmail())
// ...
->htmlTemplate('emails/signup.html.twig')
+ ->textTemplate('emails/signup.txt.twig')
// ...
;
Embedding Images
Instead of dealing with the <img src="cid: ...">
syntax explained in the
previous sections, when using Twig to render email contents you can refer to
image files as usual. First, to simplify things, define a Twig namespace called
images
that points to whatever directory your images are stored in:
1 2 3 4 5 6 7
# config/packages/twig.yaml
twig:
# ...
paths:
# point this wherever your images live
'%kernel.project_dir%/assets/images': images
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:twig="http://symfony.com/schema/dic/twig"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
<twig:config>
<!-- ... -->
<!-- point this wherever your images live -->
<twig:path namespace="images">%kernel.project_dir%/assets/images</twig:path>
</twig:config>
</container>
1 2 3 4 5 6 7 8
// config/packages/twig.php
$container->loadFromExtension('twig', [
// ...
'paths' => [
// point this wherever your images live
'%kernel.project_dir%/assets/images' => 'images',
],
]);
Now, use the special email.image()
Twig helper to embed the images inside
the email contents:
1 2 3 4 5
{# '@images/' refers to the Twig namespace defined earlier #}
<img src="{{ email.image('@images/logo.png') }}" alt="Logo">
<h1>Welcome {{ email.toName }}!</h1>
{# ... #}
Inlining CSS Styles
Designing the HTML contents of an email is very different from designing a
normal HTML page. For starters, most email clients only support a subset of all
CSS features. In addition, popular email clients like Gmail don't support
defining styles inside <style> ... </style>
sections and you must inline
all the CSS styles.
CSS inlining means that every HTML tag must define a style
attribute with
all its CSS styles. This can make organizing your CSS a mess. That's why Twig
provides a CssInlinerExtension
that automates everything for you. Install
it with:
1
$ composer require twig/extra-bundle twig/cssinliner-extra
The extension is enabled automatically. To use it, wrap the entire template
with the inline_css
filter:
1 2 3 4 5 6 7 8 9 10 11
{% apply inline_css %}
<style>
{# here, define your CSS styles as usual #}
h1 {
color: #333;
}
</style>
<h1>Welcome {{ email.toName }}!</h1>
{# ... #}
{% endapply %}
Using External CSS Files
You can also define CSS styles in external files and pass them as arguments to the filter:
1 2 3 4
{% apply inline_css(source('@css/email.css')) %}
<h1>Welcome {{ username }}!</h1>
{# ... #}
{% endapply %}
You can pass unlimited number of arguments to inline_css()
to load multiple
CSS files. For this example to work, you also need to define a new Twig namespace
called css
that points to the directory where email.css
lives:
1 2 3 4 5 6 7
# config/packages/twig.yaml
twig:
# ...
paths:
# point this wherever your css files live
'%kernel.project_dir%/assets/css': css
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:twig="http://symfony.com/schema/dic/twig"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
<twig:config>
<!-- ... -->
<!-- point this wherever your css files live -->
<twig:path namespace="css">%kernel.project_dir%/assets/css</twig:path>
</twig:config>
</container>
1 2 3 4 5 6 7 8
// config/packages/twig.php
$container->loadFromExtension('twig', [
// ...
'paths' => [
// point this wherever your css files live
'%kernel.project_dir%/assets/css' => 'css',
],
]);
Rendering Markdown Content
Twig provides another extension called MarkdownExtension
that lets you
define the email contents using Markdown syntax. To use this, install the
extension and a Markdown conversion library (the extension is compatible with
several popular libraries):
1 2
# instead of league/commonmark, you can also use erusev/parsedown or michelf/php-markdown
$ composer require twig/extra-bundle twig/markdown-extra league/commonmark
The extension adds a markdown_to_html
filter, which you can use to convert parts or
the entire email contents from Markdown to HTML:
1 2 3 4 5 6 7 8 9
{% apply markdown_to_html %}
Welcome {{ email.toName }}!
===========================
You signed up to our site using the following email:
`{{ email.to[0].address }}`
[Click here to activate your account]({{ url('...') }})
{% endapply %}
Inky Email Templating Language
Creating beautifully designed emails that work on every email client is so complex that there are HTML/CSS frameworks dedicated to that. One of the most popular frameworks is called Inky. It defines a syntax based on some HTML-like tags which are later transformed into the real HTML code sent to users:
1 2 3 4 5 6
<!-- a simplified example of the Inky syntax -->
<container>
<row>
<columns>This is a column.</columns>
</row>
</container>
Twig provides integration with Inky via the InkyExtension
. First, install
the extension in your application:
1
$ composer require twig/extra-bundle twig/inky-extra
The extension adds an inky_to_html
filter, which can be used to convert
parts or the entire email contents from Inky to HTML:
1 2 3 4 5 6 7 8 9 10 11 12
{% apply inky_to_html %}
<container>
<row class="header">
<columns>
<spacer size="16"></spacer>
<h1 class="text-center">Welcome {{ email.toName }}!</h1>
</columns>
{# ... #}
</row>
</container>
{% endapply %}
You can combine all filters to create complex email messages:
1 2 3
{% apply inky_to_html|inline_css(source('@css/foundation-emails.css')) %}
{# ... #}
{% endapply %}
This makes use of the css Twig namespace we created
earlier. You could, for example, download the foundation-emails.css file
directly from GitHub and save it in assets/css
.
Signing and Encrypting Messages
4.4
The option to sign and/or encrypt messages was introduced in Symfony 4.4.
It's possible to sign and/or encrypt email messages applying the S/MIME standard to increase their integrity/security. Both options can be combined to encrypt a signed message and/or to sign an encrypted message.
Before signing/encrypting messages, make sure to have:
- The OpenSSL PHP extension properly installed and configured;
- A valid S/MIME security certificate.
Signing Messages
When signing a message, a cryptographic hash is generated for the entire content of the message (including attachments). This hash is added as an attachment so the recipient can validate the integrity of the received message. However, the contents of the original message are still readable for mailing agents not supporting signed messages, so you must also encrypt the message if you want to hide its contents:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
use Symfony\Component\Mime\Crypto\SMimeSigner;
use Symfony\Component\Mime\Email;
$email = (new Email())
->from('hello@example.com')
// ...
->html('...');
$signer = new SMimeSigner('/path/to/certificate.crt', '/path/to/certificate-private-key.key');
// if the private key has a passphrase, pass it as the third argument
// new SMimeSigner('/path/to/certificate.crt', '/path/to/certificate-private-key.key', 'the-passphrase');
$signedEmail = $signer->sign($email);
// now use the Mailer component to send this $signedEmail instead of the original email
The certificate and private key must be PEM encoded, and can be either created using for example OpenSSL or obtained at an official Certificate Authority (CA). The email recipient must have the CA certificate in the list of trusted issuers in order to verify the signature.
Tip
When using OpenSSL to generate certificates, make sure to add the
-addtrust emailProtection
command option.
Tip
The SMimeSigner
class defines other optional arguments to pass
intermediate certificates and to configure the signing process using a
bitwise operator options for openssl_pkcs7_sign PHP function.
Encrypting Messages
When encrypting a message, the entire message (including attachments) is encrypted using a certificate. Therefore, only the recipients that have the corresponding private key can read the original message contents:
1 2 3 4 5 6 7 8 9 10 11
use Symfony\Component\Mime\Crypto\SMimeEncrypter;
use Symfony\Component\Mime\Email;
$email = (new Email())
->from('hello@example.com')
// ...
->html('...');
$encrypter = new SMimeEncrypter('/path/to/certificate.crt');
$encryptedEmail = $encrypter->encrypt($email);
// now use the Mailer component to send this $encryptedEmail instead of the original email
You can pass more than one certificate to the SMimeEncrypter
constructor
and it will select the appropriate certificate depending on the To
option:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
$firstEmail = (new Email())
// ...
->to('jane@example.com');
$secondEmail = (new Email())
// ...
->to('john@example.com');
// the second optional argument of SMimeEncrypter defines which encryption algorithm is used
// (it must be one of these constants: https://www.php.net/manual/en/openssl.ciphers.php)
$encrypter = new SMimeEncrypter([
// key = email recipient; value = path to the certificate file
'jane@example.com' => '/path/to/first-certificate.crt',
'john@example.com' => '/path/to/second-certificate.crt',
]);
$firstEncryptedEmail = $encrypter->encrypt($firstEmail);
$secondEncryptedEmail = $encrypter->encrypt($secondEmail);
Multiple Email Transports
4.4
The option to define multiple email transports was introduced in Symfony 4.4.
You may want to use more than one mailer transport for delivery of your messages.
This can be configured by replacing the dsn
configuration entry with a
transports
entry, like:
1 2 3 4 5 6
# config/packages/mailer.yaml
framework:
mailer:
transports:
main: '%env(MAILER_DSN)%'
alternative: '%env(MAILER_DSN_IMPORTANT)%'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<!-- ... -->
<framework:config>
<framework:mailer>
<framework:transport name="main">%env(MAILER_DSN)%</framework:transport>
<framework:transport name="alternative">%env(MAILER_DSN_IMPORTANT)%</framework:transport>
</framework:mailer>
</framework:config>
</container>
1 2 3 4 5 6 7 8 9 10
// config/packages/mailer.php
$container->loadFromExtension('framework', [
// ...
'mailer' => [
'transports' => [
'main' => '%env(MAILER_DSN)%',
'alternative' => '%env(MAILER_DSN_IMPORTANT)%',
],
],
]);
By default the first transport is used. The other transports can be selected by
adding an X-Transport
header (which Mailer will remove automatically from
the final email):
1 2 3 4 5 6
// Send using first transport ("main"):
$mailer->send($email);
// ... or use the transport "alternative":
$email->getHeaders()->addTextHeader('X-Transport', 'alternative');
$mailer->send($email);
Sending Messages Async
When you call $mailer->send($email)
, the email is sent to the transport immediately.
To improve performance, you can leverage Messenger to send
the messages later via a Messenger transport.
Start by following the Messenger documentation and configuring
a transport. Once everything is set up, when you call $mailer->send()
, a
SendEmailMessage message will
be dispatched through the default message bus (messenger.default_bus
). Assuming
you have a transport called async
, you can route the message there:
1 2 3 4 5 6 7 8
# config/packages/messenger.yaml
framework:
messenger:
transports:
async: "%env(MESSENGER_TRANSPORT_DSN)%"
routing:
'Symfony\Component\Mailer\Messenger\SendEmailMessage': async
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
<!-- config/packages/messenger.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:messenger>
<framework:transport name="async">%env(MESSENGER_TRANSPORT_DSN)%</framework:transport>
<framework:routing message-class="Symfony\Component\Mailer\Messenger\SendEmailMessage">
<framework:sender service="async"/>
</framework:routing>
</framework:messenger>
</framework:config>
</container>
1 2 3 4 5 6 7 8 9 10 11
// config/packages/messenger.php
$container->loadFromExtension('framework', [
'messenger' => [
'transports' => [
'async' => '%env(MESSENGER_TRANSPORT_DSN)%',
],
'routing' => [
'Symfony\Component\Mailer\Messenger\SendEmailMessage' => 'async',
],
],
]);
Thanks to this, instead of being delivered immediately, messages will be sent to the transport to be handled later (see Messenger: Sync & Queued Message Handling).
Mailer Events
MessageEvent
MessageEvent
allows to change the Message and the Envelope before the email
is sent:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\MessageEvent;
use Symfony\Component\Mime\Email;
class MailerSubscriber implements EventSubscriberInterface
{
public static function getSubscribedEvents()
{
return [
MessageEvent::class => 'onMessage',
];
}
public function onMessage(MessageEvent $event): void
{
$message = $event->getMessage();
if (!$message instanceof Email) {
return;
}
// do something with the message
}
}
Tip
When using a MessageEvent
listener to
sign the email contents, run it as
late as possible (e.g. setting a negative priority for it) so the email
contents are not set or modified after signing them.
Development & Debugging
Disabling Delivery
While developing (or testing), you may want to disable delivery of messages
entirely. You can do this by using null://null
as the mailer DSN, either in
your .env configuration files or in
the mailer configuration file (e.g. in the dev
or test
environments):
1 2 3 4
# config/packages/dev/mailer.yaml
framework:
mailer:
dsn: 'null://null'
1 2 3 4 5 6 7 8 9 10 11 12 13 14
<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<!-- ... -->
<framework:config>
<framework:mailer dsn="null://null"/>
</framework:config>
</container>
1 2 3 4 5 6 7
// config/packages/mailer.php
$container->loadFromExtension('framework', [
// ...
'mailer' => [
'dsn' => 'null://null',
],
]);
Note
If you're using Messenger and routing to a transport, the message will still be sent to that transport.
Always Send to the same Address
Instead of disabling delivery entirely, you might want to always send emails to a specific address, instead of the real address:
1 2 3 4 5
# config/packages/dev/mailer.yaml
framework:
mailer:
envelope:
recipients: ['youremail@example.com']
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
<!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<!-- ... -->
<framework:config>
<framework:mailer>
<framework:envelope>
<framework:recipient>youremail@example.com</framework:recipient>
</framework:envelope>
</framework:mailer>
</framework:config>
</container>
1 2 3 4 5 6 7 8 9
// config/packages/mailer.php
$container->loadFromExtension('framework', [
// ...
'mailer' => [
'envelope' => [
'recipients' => ['youremail@example.com'],
],
],
]);
Write a Functional Test
To functionally test that an email was sent, and even assert the email content or headers, you can use the built in assertions:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
// tests/Controller/MailControllerTest.php
namespace App\Tests\Controller;
use Symfony\Bundle\FrameworkBundle\Test\MailerAssertionsTrait;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
class MailControllerTest extends WebTestCase
{
use MailerAssertionsTrait;
public function testMailIsSentAndContentIsOk()
{
$client = $this->createClient();
$client->request('GET', '/mail/send');
$this->assertResponseIsSuccessful();
$this->assertEmailCount(1);
$email = $this->getMailerMessage();
$this->assertEmailHtmlBodyContains($email, 'Welcome');
$this->assertEmailTextBodyContains($email, 'Welcome');
}
}