Rework mailer settings (#18982)

* `PROTOCOL`: can be smtp, smtps, smtp+startls, smtp+unix, sendmail, dummy
* `SMTP_ADDR`: domain for SMTP, or path to unix socket
* `SMTP_PORT`: port for SMTP; defaults to 25 for `smtp`, 465 for `smtps`, and 587 for `smtp+startls`
* `ENABLE_HELO`, `HELO_HOSTNAME`: reverse `DISABLE_HELO` to `ENABLE_HELO`; default to false + system hostname
* `FORCE_TRUST_SERVER_CERT`: replace the unclear `SKIP_VERIFY`
* `CLIENT_CERT_FILE`, `CLIENT_KEY_FILE`, `USE_CLIENT_CERT`: clarify client certificates here

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>

1 files changed, 35 insertions, 27 deletions

diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini
index ac0c9e9c86..367553f1fa 100644
--- a/custom/conf/app.example.ini
+++ b/custom/conf/app.example.ini
@@ -1503,30 +1503,42 @@ ROUTER = console
 ;; Prefix displayed before subject in mail
 ;SUBJECT_PREFIX =
 ;;
-;; Mail server
-;; Gmail: smtp.gmail.com:587
-;; QQ: smtp.qq.com:465
-;; As per RFC 8314 using Implicit TLS/SMTPS on port 465 (if supported) is recommended,
-;; otherwise STARTTLS on port 587 should be used.
-;HOST =
-;;
-;; Disable HELO operation when hostnames are different.
-;DISABLE_HELO =
-;;
-;; Custom hostname for HELO operation, if no value is provided, one is retrieved from system.
+;; Mail server protocol. One of "smtp", "smtps", "smtp+startls", "smtp+unix", "sendmail", "dummy".
+;; - sendmail: use the operating system's `sendmail` command instead of SMTP. This is common on Linux systems.
+;; - dummy: send email messages to the log as a testing phase.
+;; If your provider does not explicitly say which protocol it uses but does provide a port,
+;; you can set SMTP_PORT instead and this will be inferred.
+;; (Before 1.18, this was controlled via MAILER_TYPE and IS_TLS_ENABLED.)
+;PROTOCOL =
+;;
+;; Mail server address, e.g. smtp.gmail.com.
+;; For smtp+unix, this should be a path to a unix socket instead.
+;; (Before 1.18, this was combined with SMTP_PORT as HOST.)
+;SMTP_ADDR =
+;;
+;; Mail server port. Common ports are:
+;;   25:  insecure SMTP
+;;   465: SMTP Secure
+;;   587: StartTLS
+;; If no protocol is specified, it will be inferred by this setting.
+;; (Before 1.18, this was combined with SMTP_ADDR as HOST.)
+;SMTP_PORT =
+;;
+;; Enable HELO operation. Defaults to true.
+;ENABLE_HELO = true
+;;
+;; Custom hostname for HELO operation.
+;; If no value is provided, one is retrieved from system.
 ;HELO_HOSTNAME =
 ;;
-;; Whether or not to skip verification of certificates; `true` to disable verification. This option is unsafe. Consider adding the certificate to the system trust store instead.
-;SKIP_VERIFY = false
+;; If set to `true`, completely ignores server certificate validation errors.
+;; This option is unsafe. Consider adding the certificate to the system trust store instead.
+;FORCE_TRUST_SERVER_CERT = false
 ;;
-;; Use client certificate
-;USE_CERTIFICATE = false
-;CERT_FILE = custom/mailer/cert.pem
-;KEY_FILE = custom/mailer/key.pem
-;;
-;; Should SMTP connect with TLS, (if port ends with 465 TLS will always be used.)
-;; If this is false but STARTTLS is supported the connection will be upgraded to TLS opportunistically.
-;IS_TLS_ENABLED = false
+;; Use client certificate in connection.
+;USE_CLIENT_CERT = false
+;CLIENT_CERT_FILE = custom/mailer/cert.pem
+;CLIENT_KEY_FILE = custom/mailer/key.pem
 ;;
 ;; Mail from address, RFC 5322. This can be just an email address, or the `"Name" <email@example.com>` format
 ;FROM =
@@ -1534,19 +1546,15 @@ ROUTER = console
 ;; Sometimes it is helpful to use a different address on the envelope. Set this to use ENVELOPE_FROM as the from on the envelope. Set to `<>` to send an empty address.
 ;ENVELOPE_FROM =
 ;;
-;; Mailer user name and password
-;; Please Note: Authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via STARTTLS) or `HOST=localhost`.
+;; Mailer user name and password, if required by provider.
 ;USER =
 ;;
 ;; Use PASSWD = `your password` for quoting if you use special characters in the password.
 ;PASSWD =
 ;;
-;; Send mails as plain text
+;; Send mails only in plain text, without HTML alternative
 ;SEND_AS_PLAIN_TEXT = false
 ;;
-;; Set Mailer Type (either SMTP, sendmail or dummy to just send to the log)
-;MAILER_TYPE = smtp
-;;
 ;; Specify an alternative sendmail binary
 ;SENDMAIL_PATH = sendmail
 ;;