diff --git a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
index ed843ccc9bbd2..4c4579f9ebf95 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
@@ -179,6 +179,29 @@ work without changes. Routes that set the header by its literal string value
 (for example `setHeader("SEARCH_QUERY", ...)`) must be updated to use the
 new value (`setHeader("CamelElasticsearchSearchQuery", ...)`).
 
+=== camel-mail
+
+The SMTP producer no longer extracts dynamic JavaMail session properties from message headers by
+default. Previously any message header whose key started with `mail.smtp.` was applied to a
+per-message `JavaMailSender`, which meant an upstream producer that mapped untrusted input into the
+exchange header map (for example `platform-http` query parameters, JMS or Kafka messages from
+untrusted producers) could override transport-security settings such as `mail.smtp.ssl.trust` or
+`mail.smtp.starttls.enable`, or redirect the SMTP connection.
+
+This behaviour is now disabled by default. Routes that legitimately rely on per-message
+`mail.smtp.*` headers must opt back in on the endpoint:
+
+[source,java]
+----
+.to("smtp://mymailserver:1234?useJavaMailSessionPropertiesFromHeaders=true");
+----
+
+Even with the opt-in, route authors should still strip the namespace with
+`removeHeaders("mail.smtp.*")` between any untrusted ingress and the mail producer.
+
+In addition, the inbound `MailHeaderFilterStrategy` now blocks the `mail.smtp.` / `mail.smtps.`
+prefix as well, so an external mail message can no longer inject these into a downstream exchange.
+
 == Upgrading from 4.14.2 to 4.14.3
 
 === camel-tika