diff --git a/docs/src/main/asciidoc/mailer-reference.adoc b/docs/src/main/asciidoc/mailer-reference.adoc
index f90c5ab62a8b6..baf7175894a2d 100644
--- a/docs/src/main/asciidoc/mailer-reference.adoc
+++ b/docs/src/main/asciidoc/mailer-reference.adoc
@@ -418,6 +418,8 @@ quarkus.mailer.start-tls=REQUIRED
 quarkus.mailer.trust-all=true
 ----
 
+IMPORTANT: To use `START_TLS`, make sure you set `tls` to `false` and `start-tls` to `REQUIRED` or `OPTIONAL`.
+
 === Configuring SSL/TLS
 
 To establish a TLS connection, you need to configure a _named_ configuration using the xref:./tls-registry-reference.adoc[TLS registry]: