From 69e0ddd8b7c9fb0babe5964c61e68e0b4789d831 Mon Sep 17 00:00:00 2001
From: Wojciech Kania <wojciech.kania@gmail.com>
Date: Mon, 2 Sep 2024 00:00:12 +0200
Subject: [PATCH] [Mailer] Mention the SentMessageEvent and FailedMessageEvent
 in the debug section

---
 mailer.rst | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/mailer.rst b/mailer.rst
index eafd542e2f3..af7b7b4fae9 100644
--- a/mailer.rst
+++ b/mailer.rst
@@ -802,6 +802,8 @@ Catch that exception to recover from the error or to display some message::
         // error message or try to resend the message
     }
 
+.. _mailer-debugging-emails:
+
 Debugging Emails
 ----------------
 
@@ -810,6 +812,9 @@ The :class:`Symfony\\Component\\Mailer\\SentMessage` object returned by the
 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.
+Access to :class:`Symfony\\Component\\Mailer\\SentMessage` can also be obtained by listening
+to the :ref:`SentMessageEvent <mailer-sent-message-event>`, and to ``getDebug()`` by listening
+to the :ref:`FailedMessageEvent <mailer-failed-message-event>`."
 
 .. note::
 
@@ -1712,6 +1717,8 @@ and their priorities:
 
     $ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\MessageEvent"
 
+.. _mailer-sent-message-event:
+
 SentMessageEvent
 ~~~~~~~~~~~~~~~~
 
@@ -1722,16 +1729,17 @@ SentMessageEvent
     The ``SentMessageEvent`` event was introduced in Symfony 6.2.
 
 ``SentMessageEvent`` allows you to act on the :class:`Symfony\\Component\\\Mailer\\\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::
+class to access the original message (``getOriginalMessage()``) and some
+:ref:`debugging information <mailer-debugging-emails>` (``getDebug()``) such as the HTTP calls
+made by the HTTP transports, which is useful for debugging errors::
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Symfony\Component\Mailer\Event\SentMessageEvent;
 
     public function onMessage(SentMessageEvent $event): void
     {
-        $message = $event->getMessage();
+        // e.g you can get mail id
+        $event->getMessage();
 
         // do something with the message
     }
@@ -1743,6 +1751,8 @@ and their priorities:
 
     $ php bin/console debug:event-dispatcher "Symfony\Component\Mailer\Event\SentMessageEvent"
 
+.. _mailer-failed-message-event:
+
 FailedMessageEvent
 ~~~~~~~~~~~~~~~~~~
 
@@ -1752,15 +1762,21 @@ FailedMessageEvent
 
     The ``FailedMessageEvent`` event was introduced in Symfony 6.2.
 
-``FailedMessageEvent`` allows acting on the the initial message in case of a failure::
+``FailedMessageEvent`` allows acting on the the initial message in case of a failure and some
+:ref:`debugging information <mailer-debugging-emails>` (``getDebug()``) such as the HTTP calls made
+by the HTTP transports, which is useful for debugging errors::
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Symfony\Component\Mailer\Event\FailedMessageEvent;
+    use Symfony\Component\Mailer\Exception\TransportExceptionInterface;
 
     public function onMessage(FailedMessageEvent $event): void
     {
         // e.g you can get more information on this error when sending an email
-        $event->getError();
+        $error = $event->getError();
+        if ($error instanceof TransportExceptionInterface) {
+            $error->getDebug();
+        }
 
         // do something with the message
     }