feature #14083 Complete documentation about mailer integration (l-vo)

This PR was submitted for the 5.x branch but it was squashed and merged into the 5.2 branch instead.

Discussion
----------

Complete documentation about mailer integration

- Complete framework config reference with `Mailer` (based on #14087 plus `message_bus` and `headers` that was added after 4.4)
- Add documentation about `native` DSN protocol (symfony/symfony#36131)

Close #14066

Commits
-------

a389dfb Complete documentation about mailer integration

Author: wouterj

mailer.rst

@@ -73,14 +73,20 @@ over SMTP by configuring the DSN in your ``.env`` file (the ``user``,
 Using Built-in Transports
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-============  ========================================  ==============================
+.. versionadded:: 5.2
+
+    The native protocol was introduced in Symfony 5.2.
+
+============  ========================================  ==============================================================
 DSN protocol  Example                                   Description
-============  ========================================  ==============================
-smtp          ``smtp://user:pass@smtp.example.com:25``  Mailer uses an SMTP server to
-                                                        send emails
-sendmail      ``sendmail://default``                    Mailer uses the local sendmail
-                                                        binary to send emails
-============  ========================================  ==============================
+============  ========================================  ==============================================================
+smtp          ``smtp://user:pass@smtp.example.com:25``  Mailer uses an SMTP server to send emails
+sendmail      ``sendmail://default``                    Mailer uses the local sendmail binary to send emails
+native        ``native://default``                      Mailer uses the sendmail binary and options configured
+                                                        in the ``sendmail_path`` setting of ``php.ini``. On Windows
+                                                        hosts, Mailer fallbacks to ``smtp`` and ``smtp_port``
+                                                        ``php.ini`` settings when ``sendmail_path`` is not configured.
+============  ========================================  ==============================================================
 
 Using a 3rd Party Transport
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

reference/configuration/framework.rst

@@ -184,6 +184,8 @@ Configuration
     * `sender`_
     * `recipients`_
 
+  * :ref:`headers <mailer-headers>`
+
 * `php_errors`_
 
   * `log`_
@@ -927,8 +929,6 @@ This setting is automatically set to true when one of the child settings is conf
 
 .. _http-headers:
 
-.. _http-headers:
-
 headers
 .......
 
@@ -3091,6 +3091,20 @@ recipients set in the code.
             ]);
         };
 
+.. _mailer-headers:
+
+headers
+.......
+
+.. versionadded:: 5.2
+
+    The ``headers`` mailer option was introduced in Symfony 5.2.
+
+**type**: ``array``
+
+Headers to add to emails. The key (``name`` attribute in xml format) is the
+header name and value the header value.
+
 workflows
 ~~~~~~~~~