New in Symfony 6.2: More Extensible Mailer

New Mailer Sending Events

We've added two new events related to email sending called SentMessageEvent and FailedMessageEvent. The SentMessageEvent allows you to act on the SentMessage object to access the original message (call getOriginalMessage()) and to get debugging information (call getDebug()) such as the HTTP calls made by the HTTP transports.

The FailedMessageEvent allows to act on the original email message that couldn't be sent for some error. Call its getError() method to know the error details.

Changing Bus Dynamically

Sometimes, the decision to send an email via some transport or another is done dynamically and can't be known beforehand. In Symfony 6.2, you can change the bus used to send the email message dynamically. To do so, add the X-Bus-Transport header to your message and pass the name of the new transport:

$email = (new Email())
    ->getHeaders()
        ->addTextHeader('X-Bus-Transport', 'async')
    // ...
;

Injecting Stamps When Sending Emails via Messenger

In Symfony 6.2 we've introduced a new QueuingMessageEvent that allows adding Messenger stamps before the email is sent to the Messenger bus. The listeners of this event can add stamps, generate logs, etc. but they can't change the message or the envelope (if you need to change that, use the MessageEvent):

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

Custom HTML to Text Conversion

The Mailer component can automatically generate a text version of an HTML e-mail using the league/html-to-markdown package. In Symfony 6.2 we're improving this feature to make the HTML-to-Markdown conversion configurable.

Use the following config option to pass the ID of the service that will perform the conversion (your service must implement HtmlToTextConverterInterface):

# config/packages/twig.yaml
twig:
    # ...
    mailer:
        html_to_text_converter: App\Mailer\MyCustomHtmlToTextConverter

Simplify Adding Parts to an Email

In order to reduce the cyclomatic complexity of the Email class, we're introducing a new addPart() method which aims to replace several related methods: attach(), attachFromPath(), embed(), embedFromPath() and attachPart(). The old methods are not deprecated, but consider using the addPart() method for new developments:

use Symfony\Component\Mime\Email;
 use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Component\Mime\Part\File;

 $email = (new Email())
     // ...
-    ->attachFromPath('/path/to/documents/terms-of-use.pdf')
+    ->addPart(new DataPart(new BodyFile('/path/to/documents/terms-of-use.pdf')))
-    ->embed(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png')
+    ->addPart((new DataPart(fopen('/path/to/images/logo.png', 'r'), 'logo', 'image/png'))->asInline())
-    ->embedFromPath('/path/to/images/signature.gif', 'footer-signature', 'image/gif')
+    ->addPart((new DataPart(new File('/path/to/images/signature.gif', 'footer-signature', 'image/gif')))->asInline())
 ;