CAMEL-24848: Fix mail useHeader* option defaults by Brijesh-Thakkar · Pull Request #26628 · apache/camel

Brijesh-Thakkar · 2026-09-20T14:02:09Z

Description

The Mail component documentation incorrectly stated that the
useHeaderRecipients, useHeaderFrom, useHeaderSubject, and
useHeaderReplyTo options default to true.

These options were intentionally changed to default to false by
CAMEL-23747 as part of the secure-by-default behavior. However, the
setter Javadocs and generated component documentation still described
the old defaults.

This change:

Updates the four setter Javadocs to document the false defaults.
Updates mail-component.adoc to document the current defaults and
the behavior when these options are explicitly set to true.
Regenerates the Mail component metadata with defaultValue: false
and corrected descriptions.
Preserves the existing secure-by-default runtime behavior.

Target

I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

JIRA issue: CAMEL-24848

Apache Camel coding standards and style

I checked that the commit has a meaningful subject line and body.
I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

The full root build was not completed. A scoped Camel Mail build was
successfully run with:

./mvnw install -DskipTests -pl components/camel-mail

The focused test also passed:

MailHeaderOverrideOptionsTest: 11 tests, 0 failures, 0 errors.

All generated Mail component metadata changes are included in this PR.

AI-assisted contributions

This PR was prepared with assistance from OpenCode using the Nemotron 3.5
model, operated by Brijesh Thakkar.

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

Initialize header-handling fields to true by default · New

What changed in this PR

Updates Camel Mail metadata so four header-override options advertise their documented default of true.

Changes:

Adds defaultValue = "true" to four @UriParam annotations.
Regenerates metadata for SMTP, SMTPS, POP3, POP3S, IMAP, and IMAPS.

File	Description
components/camel-mail/src/main/java/org/apache/camel/component/mail/MailConfiguration.java	Updated as part of this pull request.
components/camel-mail/src/generated/resources/META-INF/org/apache/camel/component/mail/smtps.json	Updated as part of this pull request.
components/camel-mail/src/generated/resources/META-INF/org/apache/camel/component/mail/smtp.json	Updated as part of this pull request.
components/camel-mail/src/generated/resources/META-INF/org/apache/camel/component/mail/pop3s.json	Updated as part of this pull request.
components/camel-mail/src/generated/resources/META-INF/org/apache/camel/component/mail/pop3.json	Updated as part of this pull request.
components/camel-mail/src/generated/resources/META-INF/org/apache/camel/component/mail/imaps.json	Updated as part of this pull request.
components/camel-mail/src/generated/resources/META-INF/org/apache/camel/component/mail/imap.json	Updated as part of this pull request.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

    @UriParam(label = "producer,advanced,security", security = "insecure:ssl")
    private boolean useJavaMailSessionPropertiesFromHeaders;
-    @UriParam(label = "producer")
+    @UriParam(defaultValue = "true", label = "producer")


gnodet-bot

The intention here is right — the generated metadata is inconsistent with the field declarations — but the diagnosis is inverted. This PR treats the current defaultValue: false in the JSON files as a bug to fix; it's actually the correct runtime state.

See commit e027f1836524c (CAMEL-23747, June 2026): the defaults were deliberately changed from true to false for secure-by-default behaviour. Allowing untrusted Exchange headers (e.g. from an HTTP consumer) to override configured mail recipients, sender, subject, and reply-to by default enables email redirection attacks. The change also removed = true from the field initializers and defaultValue = "true" from the @UriParam annotations at the same time.

The actual documentation bug is the opposite: the @param Javadoc on the four setters still says "Defaults to true." — which is now wrong. That text needs to be updated to say "Defaults to false." The generated JSON files already report defaultValue: false correctly and must not be changed.

So the fix needed is:

Update the four Javadoc descriptions (in MailConfiguration.java) to remove "Defaults to true." — change to "Defaults to false. Set to true to allow..." (reversing the opt-in language)
Regenerate the JSON metadata (the descriptions in the JSON files embed the same "Defaults to true." text, so they also need to change after the Javadoc is fixed)
No changes to @UriParam(defaultValue = ...) — those should remain absent/false

The PR checkbox confirming mvn clean install -DskipTests was run locally is unchecked with an explanation that the build failed in an unrelated module. Please attempt a mvn install -DskipTests -pl components/camel-mail scoped build at minimum before re-submitting.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

gnodet-bot · 2026-09-20T14:42:29Z

    @UriParam(label = "producer,advanced,security", security = "insecure:ssl")
    private boolean useJavaMailSessionPropertiesFromHeaders;
-    @UriParam(label = "producer")
+    @UriParam(defaultValue = "true", label = "producer")


⚠️ Incorrect fix direction. Commit e027f1836524c (CAMEL-23747) deliberately removed defaultValue = "true" here and reset the field initializer to false for secure-by-default. Adding it back undoes that security hardening without any corresponding = true on the field — the annotation attribute is documentation metadata only and does not affect the runtime value.

The actual bug is in the Javadoc: the setter descriptions for all four options still say "Defaults to true." That text should be updated to reflect the current false default.

Croway · 2026-09-20T14:43:54Z

The useHeader* defaults are correct as-is, false is correct and introduced by CAMEL-23747, and it's documented as a breaking change in the 4.21 upgrade guide. Changing defaultValue to true would make the catalog, IDE completion and the generated starter disagree with the code, and regenerating camel-spring-boot would silently flip Spring Boot users back to header-overrides-enabled.

Could you revert the MailConfiguration annotation change and instead update:

the four setter javadocs (MailConfiguration.java:731,743,755,767) — "Defaults to false. Set to true to let message headers override…"; these feed the description in the JSONs
mail-component.adoc:303-306 — Default column to false; the "Effect when set to false" column now describes the default, so it needs re-heading or inverting
mail-component.adoc:308 — drop "All four default to true so existing behaviour is preserved"

Brijesh-Thakkar · 2026-09-20T14:45:45Z

@gnodet @Croway
thanks for the review, i understood what changes are required
will do the suggested changes
Thanks again

gnodet-bot

The re-push fully addresses all feedback from the previous review.

Prior findings — status:

✅ @UriParam annotations: no defaultValue = "true" added — the four fields remain plain @UriParam(label = "producer") with no defaultValue attribute, so the annotation processor correctly infers false. Runtime behaviour unchanged.
✅ JSON metadata defaultValue field: stays at false across all six descriptor files (imap, imaps, pop3, pop3s, smtp, smtps).
✅ JSON description strings: correctly updated from "Defaults to true. Set to false to always use..." → "Defaults to false. Set to true to let message headers override..." — matches the actual runtime default.
✅ MailConfiguration.java setter Javadoc: all four updated to "Defaults to false. Set to true to let..." — no longer contradicts the code.
✅ mail-component.adoc table: Default column now shows false; column header changed to "Effect when set to true"; footer sentence updated to drop the now-incorrect "existing behaviour is preserved" phrasing.

No issues with field initializers, annotation processor outputs, or Spring Boot catalog consistency. The change is a doc/metadata-only fix with no runtime impact.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Brijesh-Thakkar · 2026-09-20T23:42:42Z

@Croway @gnodet Please review this PR and if the required changes are done and all ci are passsing , maintainer could merge it
Thanks

github-actions · 2026-09-21T07:19:34Z

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

First-time contributors require MANUAL approval for the GitHub Actions to run
You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

github-actions · 2026-09-21T07:40:20Z

⚠️ Generated files are out of date

The CI build regenerated files that are not committed on this PR.

If Allow edits from maintainers is enabled, a maintainer bot will automatically
push a "Regen" commit to this branch shortly.

Otherwise, you can apply the patch manually — the missing changes are available
as the regen-patch artifact of that run:

gh pr checkout 26628 --repo apache/camel
gh run download 35526400154 --repo apache/camel -n regen-patch
git apply --index regen.patch && rm regen.patch pr-number
git commit -m "Regen" && git push

Alternatively, run ./etc/scripts/regen.sh locally and commit the resulting changes.
If the patch does not apply cleanly, update the branch from the base branch first —
the patch was generated against the merge with the base branch.

oscerd

Thanks — the change itself is correct (the useHeader* options do default to false, and the stale descriptions needed exactly this fix). Heads-up on why CI is red: the build (25) job fails at "Fail if there are uncommitted changes" because the description change was regenerated only into the module-level files, not the catalog and DSL layers. A @UriParam description change propagates to all three.

Still needing regeneration and commit:

Catalog copies: catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/{imap,imaps,pop3,pop3s,smtp,smtps}.json and catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/mail-component.adoc
DSL builders: dsl/camel-componentdsl/src/generated/java/org/apache/camel/builder/component/dsl/{Imap,Imaps,Pop3,Pop3s,Smtp,Smtps}ComponentBuilderFactory.java and dsl/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/MailEndpointBuilderFactory.java

Note that -Dquickly skips the DSL generation, which is likely why these were missed. A normal build that reaches the dsl and catalog modules regenerates them (build components/camel-mail, then the dsl/catalog modules) — commit the updated files and the uncommitted-changes check will pass. Once that's in, this looks good to me.

This is a rules-and-conventions review and does not replace specialized AI review tools or static analysis.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of oscerd

davsclaus

Thanks for the fix, @Brijesh-Thakkar - the content is right: Javadoc, the adoc table and the component JSON descriptions now all say false, which matches the CAMEL-23747 secure-by-default change, and there is no runtime change.

+1 to what @oscerd wrote above: the only thing keeping CI red is that the same description change also has to be regenerated into the catalog copies (catalog/camel-catalog/src/generated/...) and the component-dsl / endpoint-dsl builders under dsl/. I checked on main and there are 6 of those generated files still carrying the old "Defaults to true" text, so once those are regenerated and committed this is good to go.

Claude Code on behalf of @davsclaus

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

gnodet-bot

The re-push completes the regeneration from the previous round.

What changed in this push: The catalog/docs/mail-component.adoc (generated catalog copy) and MailEndpointBuilderFactory.java were not regenerated in the prior push — this commit adds them, propagating the corrected descriptions throughout all generated artifacts.

Correctness check on the new additions:

catalog/camel-catalog/.../docs/mail-component.adoc: table column flipped to "Effect when set to true", defaults corrected to false — matches the source adoc.
MailEndpointBuilderFactory.java: all 8 Javadoc blocks (4 options × 2 overloads each) updated consistently to "Defaults to false. Set to true to let..." — matches MailConfiguration.java setters and the JSON descriptors.

No logic changes. All generated artifacts are now consistent with the field declarations (private boolean useHeader* — bare Java boolean = false). No issues.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

Copilot AI lite review requested due to automatic review settings September 20, 2026 14:02

Copilot started reviewing on behalf of Brijesh-Thakkar September 20, 2026 14:02 View session

Copilot AI reviewed Sep 20, 2026

View reviewed changes

gnodet-bot suggested changes Sep 20, 2026

View reviewed changes

CAMEL-24848: Fix mail header option defaults

f47e441

Brijesh-Thakkar force-pushed the CAMEL-24848-fix-mail-header-option-docs branch from 001e4bf to f47e441 Compare September 20, 2026 17:36

gnodet-bot approved these changes Sep 20, 2026

View reviewed changes

Brijesh-Thakkar requested a balanced review from Copilot September 20, 2026 17:41

Copilot AI reviewed Sep 20, 2026

github-actions Bot added components docs labels Sep 21, 2026

oscerd reviewed Sep 21, 2026

View reviewed changes

Regen

2005bdb

davsclaus reviewed Sep 21, 2026

View reviewed changes

github-actions Bot added catalog dsl labels Sep 21, 2026

gnodet-bot approved these changes Sep 21, 2026

View reviewed changes

Navigation Menu

CAMEL-24848: Fix mail useHeader* option defaults - #26628

CAMEL-24848: Fix mail useHeader* option defaults#26628
Brijesh-Thakkar wants to merge 2 commits into
apache:mainfrom
Brijesh-Thakkar:CAMEL-24848-fix-mail-header-option-docs

Brijesh-Thakkar commented Sep 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

gnodet-bot left a comment

Uh oh!

gnodet-bot Sep 20, 2026

Uh oh!

Croway commented Sep 20, 2026

Uh oh!

Brijesh-Thakkar commented Sep 20, 2026

Uh oh!

gnodet-bot left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Brijesh-Thakkar commented Sep 20, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

oscerd left a comment

Uh oh!

davsclaus left a comment

Uh oh!

gnodet-bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

Brijesh-Thakkar commented Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Target

Tracking

Apache Camel coding standards and style

AI-assisted contributions

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

gnodet-bot left a comment

Choose a reason for hiding this comment

Uh oh!

gnodet-bot Sep 20, 2026

Choose a reason for hiding this comment

Uh oh!

Croway commented Sep 20, 2026

Uh oh!

Brijesh-Thakkar commented Sep 20, 2026

Uh oh!

gnodet-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Brijesh-Thakkar commented Sep 20, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

⚠️ Generated files are out of date

Uh oh!

oscerd left a comment

Choose a reason for hiding this comment

Uh oh!

davsclaus left a comment

Choose a reason for hiding this comment

Uh oh!

gnodet-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Brijesh-Thakkar commented Sep 20, 2026 •

edited

Loading