The configuration options for e-mail sending TLS are awful — improve them by making them clearer and in most cases default to the right option

[matrixbot]

This issue has been migrated from #15126.

---

I've run into a lot of confused admins recently, because the way we configure TLS for our e-mail sending is awful.

• require_transport_security: true enables Explicit TLS (STARTTLS).
  • at least 'require' accurately describes that we expect the server to offer a capability and require it to be there.
• force_tls: true enables Implicit TLS.
  • force is such a weird word to describe Implicit TLS.

I'd much rather see us adopt a single config option, tls_mode, with the following options:

• explicit or starttls — chosen by default if the port is 587 or 25.
• implicit— chosen by default if the port is 465.
• off — never chosen by default.
• for other port numbers: require the admin to choose

In the best and most reasonable case, the admin would never need to touch this option(!) because basically everyone uses these standard ports!!!

A little bit of effort would be required to support the old options transitionally, but the documentation for this option could be much clearer — such as providing a table for admins that really need to configure e-mail on a random port (rather than having options with no obvious difference discernible from the name, even to e-mail experts). And most people would fall right into the 'well-known port? Automatic configuration' happy path!

[jsma]

I agree with the title of this issue ;)

The example configuration in the documentation also needs to be fixed:

synapse/docs/usage/configuration/config_documentation.md

Lines 727 to 737 in 7c805f0

	Example configuration:
	```yaml
	email:
	smtp_host: mail.server
	smtp_port: 587
	smtp_user: "exampleusername"
	smtp_pass: "examplepassword"
	force_tls: true
	require_transport_security: true
	enable_tls: false

These settings will prevent Synapse from starting. I was only able to get email sending to work with the following:

email:
  smtp_host: mail.server
  smtp_port: 587
  smtp_user: "exampleusername"
  smtp_pass: "examplepassword"
  force_tls: false # changed from `true`
  require_transport_security: true
  enable_tls: true # changed from `false`