From 7dbe95061e084d72311921ca2a1869aaa1ab451e Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Sun, 23 Oct 2022 12:23:00 +0200
Subject: [PATCH] Add docs about Mailer stamps

---
 mailer.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/mailer.rst b/mailer.rst
index 8c94cc75d1a..c15f2833083 100644
--- a/mailer.rst
+++ b/mailer.rst
@@ -1429,8 +1429,8 @@ MessageEvent
 
 **Event Class**: :class:`Symfony\\Component\\Mailer\\Event\\MessageEvent`
 
-``MessageEvent`` allows to change the Message and the Envelope before the email
-is sent::
+``MessageEvent`` allows to change the Mailer message and the envelope before
+the email is sent::
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Symfony\Component\Mailer\Event\MessageEvent;
@@ -1459,6 +1459,48 @@ and their priorities:
 
     $ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\MessageEvent"
 
+QueuingMessageEvent
+~~~~~~~~~~~~~~~~~~~
+
+**Event Class**: :class:`Symfony\\Component\\Mailer\\Event\\QueuingMessageEvent`
+
+.. versionadded:: 6.2
+
+    The ``QueuingMessageEvent`` class was introduced in Symfony 6.2.
+
+``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::
+
+    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:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\QueuingMessageEvent"
+
 SentMessageEvent
 ~~~~~~~~~~~~~~~~