Skip to content

[Mailer] Document require_tls option #20701

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: 7.3
Choose a base branch
from
+23 −0
Open

[Mailer] Document require_tls option #20701

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e1048bb
[Mailer] Document require_tls option
ssddanbrown Mar 1, 2025
7a2eb90
[Mailer] Moved version notice to after note for require_tls
ssddanbrown Mar 19, 2025
4871fd0
[Mailer] Tweaked version notice for require_tls option
ssddanbrown Mar 24, 2025
4cb9b50
[Mailer] Updated heading for require_tls option
ssddanbrown Apr 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions mailer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,6 +416,29 @@ setting the ``auto_tls`` option to ``false`` in the DSN::
the Internet, but it can be useful when both the application and the SMTP
server are in a secured network, where there is no need for additional encryption.

.. note::

This setting only works when the ``smtp://`` protocol is used.

Require use of TLS
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe:

Suggested change
Require use of TLS
Enforce TLS

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy to change if preferred, but Enforce feels slightly less accurate to me. Enforce sounds like it'd change/force the connection in some manner and/or force TLS upon the whole connection process, whereas this option doesn't change the connection in any way, just ensures it's eventually used.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand your concern about the term "Enforce" and I agree with you.
What do you think about "Ensure TLS" instead? It might better reflect that the option guarantees the use of TLS without actively altering the connection.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Spomky Sorry for the late response. I agree that "Ensure TLS" would be better. I've updated the heading to that.

~~~~~~~~~~~~~~~~~~

.. versionadded:: 7.3

The option to require TLS was introduced in Symfony 7.3.

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:[email protected]?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.
Expand Down