Sending Emails with Mailer ¶

Using Built-in Transports ¶

Using a 3rd Party Transport ¶

Instead of using your own SMTP server or sendmail binary, you can send emails via a third-party provider:

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:

1
2

# .env
MAILER_DSN=mailgun+https://KEY:DOMAIN@requestbin.com

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.

TLS Peer Verification ¶

By default, SMTP transports perform TLS peer verification. This behavior is configurable with the verify_peer option. Although it's not recommended to disable this verification for security reasons, it can be useful while developing the application or when using a self-signed certificate:

1

$dsn = 'smtp://user:pass@smtp.example.com?verify_peer=0';

Other Options ¶

command

Command to be executed by sendmail transport:

sendmail トランスポートによって実行されるコマンド:

1	$dsn = 'sendmail://default?command=/usr/sbin/sendmail%20-oi%20-t'

local_domain

The domain name to use in HELO command:

HELO コマンドで使用するドメイン名:

1	$dsn = 'smtps://smtp.example.com?local_domain=example.org'

restart_threshold

The maximum number of messages to send before re-starting the transport. It can be used together with restart_threshold_sleep:

トランスポートを再開する前に送信するメッセージの最大数。 restart_threshold_sleep と一緒に使用できます。

1	$dsn = 'smtps://smtp.example.com?restart_threshold=10&restart_threshold_sleep=1'

restart_threshold_sleep

The number of seconds to sleep between stopping and re-starting the transport. It's common to combine it with restart_threshold:

トランスポートの停止と再起動の間にスリープする秒数。restart_threshold と組み合わせるのが一般的です。

1	$dsn = 'smtps://smtp.example.com?restart_threshold=10&restart_threshold_sleep=1'

ping_threshold

The minimum number of seconds between two messages required to ping the server:

サーバーへの ping に必要な 2 つのメッセージ間の最小秒数:

1	$dsn = 'smtps://smtp.example.com?ping_threshold=200'

max_per_second

The number of messages to send per second (0 to disable this limitation):

1 秒あたりに送信するメッセージの数 (この制限を無効にするには 0):

1	$dsn = 'smtps://smtp.example.com?max_per_second=2'

6.2

6.2

The max_per_second option was introduced in Symfony 6.2.

max_per_second オプションは Symfony 6.2 で導入されました。

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::create('Fabien Potencier <fabien@example.com>'))

    // ...
;

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'))
;

File Attachments ¶

Use the addPart() method with a BodyFile to add files that exist on your file system:

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Mime\Part\DataPart;
use Symfony\Component\Mime\Part\File;
// ...

$email = (new Email())
    // ...
    ->addPart(new DataPart(new File('/path/to/documents/terms-of-use.pdf')))
    // optionally you can tell email clients to display a custom name for the file
    ->addPart(new DataPart(new File('/path/to/documents/privacy.pdf'), 'Privacy Policy'))
    // optionally you can provide an explicit MIME type (otherwise it's guessed)
    ->addPart(new DataPart(new File('/path/to/documents/contract.doc'), 'Contract', 'application/msword'))
;

Alternatively you can attach contents from a stream by passing it directly to the DataPart :

1
2
3
4

$email = (new Email())
    // ...
    ->addPart(new DataPart(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 addPart() 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
    ->addPart((new DataPart(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png'))->asInline())
    // get the image contents from an existing file
    ->addPart((new DataPart(new File('/path/to/images/signature.gif'), 'footer-signature', 'image/gif'))->asInline())
;

Use the asInline() method to embed the content instead of attaching it.

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
9
10
11

$email = (new Email())
    // ...
    ->addPart((new DataPart(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png'))->asInline())
    ->addPart((new DataPart(new File('/path/to/images/signature.gif'), 'footer-signature', 'image/gif'))->asInline())

    // reference images using the syntax 'cid:' + "image embed name"
    ->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...')

    // use the same syntax for images included as HTML background images
    ->html('... <div background="cid:footer-signature"> ... </div> ...')
;

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, it is automatically generated from the HTML contents.

Symfony uses the following strategy when generating the text version of an email:

• If an explicit HTML to text converter has been configured (see twig.mailer.html_to_text_converter), it calls it;
  明示的な HTML からテキストへのコンバーターが構成されている場合 (seetwig.mailer.html_to_text_converter)、それを呼び出します。
• If not, and if you have league/html-to-markdown installed in your application, it uses it to turn HTML into Markdown (so the text email has some visual appeal);
  そうでない場合で、リーグ/html-to-markdown がアプリケーションにインストールされている場合、それを使用して HTML を Markdown に変換します (そのため、テキスト メールに視覚的な魅力があります)。
• Otherwise, it applies the strip_tags PHP function to the original HTML contents.
  それ以外の場合は、strip_tags PHP 関数を元の HTML コンテンツに適用します。

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
9

// config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig) {
    // ...

    // point this wherever your images live
    $twig->path('%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 %}

1
2
3
4

{% apply inline_css(source('@styles/email.css')) %}
    <h1>Welcome {{ username }}!</h1>
    {# ... #}
{% endapply %}

1
2
3
4
5
6
7

# config/packages/twig.yaml
twig:
    # ...

    paths:
        # point this wherever your css files live
        '%kernel.project_dir%/assets/styles': styles

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="styles">%kernel.project_dir%/assets/styles</twig:path>
    </twig:config>
</container>

1
2
3
4
5
6
7
8
9

// config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig) {
    // ...

    // point this wherever your css files live
    $twig->path('%kernel.project_dir%/assets/styles', 'styles');
};

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('@styles/foundation-emails.css')) %}
    {# ... #}
{% endapply %}

This makes use of the styles Twig namespace we created earlier. You could, for example, download the foundation-emails.css file directly from GitHub and save it in assets/styles.

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.

You can sign messages using either S/MIME or DKIM. In both cases, 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.

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

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

use Symfony\Component\Mime\Crypto\DkimSigner;
use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('hello@example.com')
    // ...
    ->html('...');

// first argument: same as openssl_pkey_get_private(), either a string with the
// contents of the private key or the absolute path to it (prefixed with 'file://')
// second and third arguments: the domain name and "selector" used to perform a DNS lookup
// (the selector is a string used to point to a specific DKIM public key record in your DNS)
$signer = new DkimSigner('file:///path/to/private-key.key', 'example.com', 'sf');
// if the private key has a passphrase, pass it as the fifth argument
// new DkimSigner('file:///path/to/private-key.key', 'example.com', 'sf', [], 'the-passphrase');

$signedEmail = $signer->sign($email);
// now use the Mailer component to send this $signedEmail instead of the original email

// DKIM signer provides many config options and a helper object to configure them
use Symfony\Component\Mime\Crypto\DkimOptions;

$signedEmail = $signer->sign($email, (new DkimOptions())
    ->bodyCanon('relaxed')
    ->headerCanon('relaxed')
    ->headersToIgnore(['Message-ID'])
    ->toArray()
);

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);

MessageEvent ¶

Event Class: MessageEvent

MessageEvent allows to change the Mailer message and the envelope before the email is sent:

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\MessageEvent;
use Symfony\Component\Mime\Email;

public function onMessage(MessageEvent $event): void
{
    $message = $event->getMessage();
    if (!$message instanceof Email) {
        return;
    }
    // do something with the message
}

Execute this command to find out which listeners are registered for this event and their priorities:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\MessageEvent"

QueuingMessageEvent ¶

Event Class: QueuingMessageEvent

QueuingMessageEvent allows to add some logic before the email is sent to the Messenger bus (this event is not dispatched when no bus is configured); it extends MessageEvent to allow adding Messenger stamps to the Messenger message sent to the bus:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\QueuingMessageEvent;
use Symfony\Component\Mime\Email;

public function onMessage(QueuingMessageEvent $event): void
{
    $message = $event->getMessage();
    if (!$message instanceof Email) {
        return;
    }
    // do something with the message (logging, ...)

    // and/or add some Messenger stamps
    $event->addStamp(new SomeMessengerStamp());
}

This event lets listeners do something before a message is sent to the queue (like adding stamps or logging) but any changes to the message or the envelope are discarded. To change the message or the envelope, listen to MessageEvent instead.

Execute this command to find out which listeners are registered for this event and their priorities:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\QueuingMessageEvent"

SentMessageEvent ¶

Event Class: SentMessageEvent

SentMessageEvent allows you to act on the SentMessage class to access the original message (getOriginalMessage()) and some debugging information (getDebug()) such as the HTTP calls made by the HTTP transports, which is useful for debugging errors:

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\SentMessageEvent;
use Symfony\Component\Mailer\SentMessage;

public function onMessage(SentMessageEvent $event): void
{
    $message = $event->getMessage();
    if (!$message instanceof SentMessage) {
        return;
    }

    // do something with the message
}

Execute this command to find out which listeners are registered for this event and their priorities:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\SentMessageEvent"

FailedMessageEvent ¶

Event Class: FailedMessageEvent

FailedMessageEvent allows acting on the the initial message in case of a failure:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\FailedMessageEvent;

public function onMessage(FailedMessageEvent $event): void
{
    // e.g you can get more information on this error when sending an email
    $event->getError();

    // do something with the message
}

Execute this command to find out which listeners are registered for this event and their priorities:

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\FailedMessageEvent"

Enabling an Email Catcher ¶

When developing locally, it is recommended to use an email catcher. If you have enabled Docker support via Symfony recipes, an email catcher is automatically configured. In addition, if you are using the Symfony local web server, the mailer DSN is automatically exposed via the symfony binary Docker integration.

Sending Test Emails ¶

Symfony provides a command to send emails, which is useful during development to test if sending emails works correctly:

1
2
3

# the only mandatory argument is the recipient address
# (check the command help to learn about its options)
$ php bin/console mailer:test someone@example.com

This command bypasses the Messenger bus, if configured, to ease testing emails even when the Messenger consumer is not running.

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
8

// config/packages/mailer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $framework->mailer()
        ->dsn('null://null');
};

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
10

// config/packages/mailer.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $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');
    }
}