minor #20186 [Mailer] Mention the SentMessageEvent and FailedMessageEvent (wkania)

This PR was merged into the 6.4 branch.

Discussion
----------

[Mailer] Mention the `SentMessageEvent` and `FailedMessageEvent`

The symfony/symfony#47080 PR was created to solve the problem of [debugging](symfony/symfony#37570) and to get [information](symfony/symfony#42108) about email after it was sent.
The section about [debugging](https://symfony.com/doc/current/mailer.html#debugging-emails) does not mention those events. Added some links for better navigation.

For example what debug returns:

```
< 220 ESMTP SYMFONY.COM
> EHLO [127.0.0.1]
< 250-smtp.symfony.com
< 250-PIPELINING
< 250-SIZE 157286400
< 250-AUTH PLAIN LOGIN PLAIN LOGIN PLAIN LOGIN
< 250-AUTH=PLAIN LOGIN PLAIN LOGIN PLAIN LOGIN
< 250-ENHANCEDSTATUSCODES
< 250-8BITMIME
< 250 SMTPUTF8
> AUTH LOGIN
< 334 VXNlcm5hbWU6
> ZXhhbXBsZUBzeW1mb255LmNvbQ==
< 334 UGFzc3dvcmQ6
> U3ltcGhvbnkg.aXMgQXdlc29tZQ==
< 235 2.7.0 Authentication successful
> MAIL FROM:<example@symfony.com>
< 250 2.1.0 Ok
> RCPT TO:<dummy@symfony.com>
< 250 2.1.5 Ok
> DATA
< 354 End data with <CR><LF>.<CR><LF>
> .
< 250 OK. ID: a20fb6ebbc54d22b
```

P.S.
I see that the checks now can find repeated words:
```
mailer.rst ✘
 1765: The word "the" is used more times in a row.
   ->  ``FailedMessageEvent`` allows acting on the the initial message in case of a failure and some
```

Commits
-------

8e3c1db [Mailer] Mention the SentMessageEvent and FailedMessageEvent in the debug section

Author: javiereguiluz

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 initial message in case of a failure::
+``FailedMessageEvent`` allows acting on 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
     }