Merge branch '7.2' into 7.3

* 7.2:
  Reword
  [Mailer] Update mailer.rst

Author: javiereguiluz

mailer.rst

@@ -875,30 +875,56 @@ Catch that exception to recover from the error or to display some message::
 Debugging Emails
 ----------------
 
-The :class:`Symfony\\Component\\Mailer\\SentMessage` object returned by the
-``send()`` method of the :class:`Symfony\\Component\\Mailer\\Transport\\TransportInterface`
-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.
+The ``send()`` method of the mailer service injected when using ``MailerInterface``
+doesn't return anything, so you can't access the sent email information. This is because
+it sends email messages **asynchronously** when the :doc:`Messenger component </messenger>`
+is used in the application.
 
-You can also access :class:`Symfony\\Component\\Mailer\\SentMessage` by listening
-to the :ref:`SentMessageEvent <mailer-sent-message-event>` and retrieve ``getDebug()``
-by listening to the :ref:`FailedMessageEvent <mailer-failed-message-event>`.
+To access information about the sent email, update your code to replace the
+:class:`Symfony\\Component\\Mailer\\MailerInterface` with
+:class:`Symfony\\Component\\Mailer\\Transport\\TransportInterface`:
 
-.. note::
+.. code-block:: diff
+
+    -use Symfony\Component\Mailer\MailerInterface;
+    +use Symfony\Component\Mailer\Transport\TransportInterface;
+     // ...
+
+     class MailerController extends AbstractController
+     {
+         #[Route('/email')]
+    -    public function sendEmail(MailerInterface $mailer): Response
+    +    public function sendEmail(TransportInterface $mailer): Response
+         {
+             $email = (new Email())
+                 // ...
+
+             $sentEmail = $mailer->send($email);
+
+             // ...
+         }
+     }
+
+The ``send()`` method of ``TransportInterface`` returns an object of type
+:class:`Symfony\\Component\\Mailer\\SentMessage`. This is because it always sends
+the emails **synchronously**, even if your application uses the Messenger component.
+
+The ``SentMessage`` object 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.
 
-    If your code used :class:`Symfony\\Component\\Mailer\\MailerInterface`, you
-    need to replace it by :class:`Symfony\\Component\\Mailer\\Transport\\TransportInterface`
-    to have the ``SentMessage`` object returned.
+You can also access the :class:`Symfony\\Component\\Mailer\\SentMessage` object
+by listening to the :ref:`SentMessageEvent <mailer-sent-message-event>`, and retrieve
+``getDebug()`` by listening to the :ref:`FailedMessageEvent <mailer-failed-message-event>`.
 
 .. note::
 
     Some mailer providers change the ``Message-Id`` when sending the email. The
-    ``getMessageId()`` method from ``SentMessage`` always returns the definitive
-    ID of the message (being the original random ID generated by Symfony or the
-    new ID generated by the mailer provider).
+    ``getMessageId()`` method from ``SentMessage`` always returns the final ID
+    of the message - whether it's the original random ID generated by Symfony or
+    a new one generated by the provider.
 
-The exceptions related to mailer transports (those which implement
+Exceptions related to mailer transports (those implementing
 :class:`Symfony\\Component\\Mailer\\Exception\\TransportException`) also provide
 this debug information via the ``getDebug()`` method.