minor #20701 [Mailer] Document require_tls option (ssddanbrown)

javiereguiluz · javiereguiluz · commit 7d360e640fa8 · 2025-05-08T10:04:13.000+02:00
This PR was squashed before being merged into the 7.3 branch. Discussion ---------- [Mailer] Document `require_tls` option For #20644. This PR documents the added SMTP `require_tls` option, as introduced in symfony/symfony#59479. I have referenced that this could throw a `TransportException` (where TLS is not achieved) but not sure if I should instead reference `TransportExceptionInterface`. Commits ------- 55217dc [Mailer] Document `require_tls` option
diff --git a/mailer.rst b/mailer.rst
@@ -420,6 +420,29 @@ setting the ``auto_tls`` option to ``false`` in the DSN::
 
     This setting only works when the ``smtp://`` protocol is used.
 
+Ensure TLS
+~~~~~~~~~~
+
+You may want to ensure TLS is used, either directly or via ``STARTTLS``,
+for sending mail over SMTP regardless of other options set or SMTP server
+support. You can set TLS as required by calling ``setRequireTls(true)``
+on the ``EsmtpTransport`` instance, or by setting the ``require_tls`` option
+to ``true`` in the DSN::
+
+    $dsn = 'smtp://user:pass@10.0.0.25?require_tls=true';
+
+When TLS is set as required, a :class:`Symfony\\Component\\Mailer\\Exception\\TransportException`
+will be thrown if a TLS connection cannot be achieved during initial communications
+with the SMTP server.
+
+.. note::
+
+    This setting only works when the ``smtp://`` protocol is used.
+
+.. versionadded:: 7.3
+
+    The ``require_tls`` option was introduced in Symfony 7.3.
+
 Binding to IPv4 or IPv6
 ~~~~~~~~~~~~~~~~~~~~~~~
 
