Contributed by Fabien Potencier
in #47080,
#47190,
#47191,
#47201,
#47462,
#47711.

In Symfony 6.2 we're making the Mailer component more extensible with features
such as new events, allowing to change the bus/transport dynamically and simplifying
how email parts are added.

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\Part\DataPart;
+use Symfony\Component\Mime\Part\File;
use Symfony\Component\Mime\Email;

$email = (new Email())
// ...
- ->attachFromPath('/path/to/documents/terms-of-use.pdf')
+ ->addPart(new DataPart(new File('/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())
;

Sponsor the Symfony project.