Skip to content

chore: the mail Kamelets can choose, move and delete the emails they read, and mail-sink takes cc, bcc and replyTo (#3170) - #3216

Merged
davsclaus merged 1 commit into
apache:mainfrom
davsclaus:ci-issue-3170-mail-options
Nov 18, 2026
Merged

davsclaus merged 1 commit into
apache:mainfrom
davsclaus:ci-issue-3170-mail-options

Conversation

@davsclaus

Copy link
Copy Markdown
Contributor

Part of #3170: mail-imap-source and ms-exchange-online-imap-oauth-source can read another folder, read emails that are already read, search, and move, copy or delete each email once it is processed. mail-sink takes cc, bcc, replyTo and contentType. Both can trust a private certificate authority.

The options

mail-imap-source and ms-exchange-online-imap-oauth-source

Option Template mapping What it does
folderName folderName: "RAW({{?folderName}})" The folder to read; INBOX when not set.
unseen (boolean) unseen: "{{?unseen}}" and searchTerm.unseen: "{{?unseen}}" false also reads the emails that are already read.
delete (boolean) delete: "{{?delete}}" Deletes each email once it is processed.
moveTo moveTo: "RAW({{?moveTo}})" Moves each email to this folder once it is processed. The folder is created if needed.
copyTo copyTo: "RAW({{?copyTo}})" Copies each email to this folder once it is processed.
peek (boolean) peek: "{{?peek}}" Keeps an email unread while it is processed. The component default is on.
skipFailedMessage (boolean) skipFailedMessage: "{{?skipFailedMessage}}" Skips an email that cannot be read at all.
searchFrom searchTerm.from: "RAW({{?searchFrom}})" Reads only the emails from this sender.
searchTo searchTerm.to: "RAW({{?searchTo}})" Reads only the emails to this To recipient.
searchSubject searchTerm.subject: "RAW({{?searchSubject}})" Reads only the emails with this text in the subject.
searchSubjectOrBody searchTerm.subjectOrBody: "RAW({{?searchSubjectOrBody}})" Reads only the emails with this text in the subject or the text.

mail-sink

Option Template mapping What it does
cc Cc header, from {{?cc}}, unless the message has ce-cc Copy recipients.
bcc Bcc header, from {{?bcc}} Blind copy recipients.
replyTo replyTo=RAW({{?replyTo}}) on the endpoint The address that replies go to.
contentType contentType=RAW({{?contentType}}) on the endpoint; when set, the Content-Type and CamelMailContentType headers are removed The type of every email, such as text/html.
  • Defaults. None of the options has a default, as in chore: mail-sink can use STARTTLS (#3170) #3174. When they are not set, the optional placeholders drop them, so the endpoint URIs are the same as on main.
  • Search without a bean. The search options use camel-mail's searchTerm.* parameters. When several are set, an email must match all of them. With a search, camel-mail takes "unread only" from the search and ignores the unseen endpoint option. So unseen is passed to both; otherwise unseen: false would have no effect once a search is set.
  • Search matching is done by the mail server. GreenMail matches searchFrom and searchTo only against a whole address (FROM "bob" finds nothing, and FROM "BOB@" is rejected with BAD). The descriptions therefore say to give the whole address. Case does not matter.
  • RAW() and patterns. Folder names and search texts keep +, spaces, & and parentheses as written. % and * are IMAP wildcards: with moveTo: "Done 100%+(y)" the server rejected the move, and the email stayed in the inbox, marked as read. So the three folder options have the pattern ^[^\r\n%*]+$. replyTo and contentType also have a pattern.
  • mail-sink recipients: a fix. camel-mail takes the recipients either all from the To, Cc and Bcc headers, or, when there is none, all from the options. On main, a ce-to or ce-cc header therefore dropped every recipient option. With to: alice and a ce-cc: bob header, the email went to bob only. A bcc option would have been lost in the same way. The Kamelet now puts the to, cc and bcc options into the headers, so a ce-to or ce-cc header replaces only its own option. Bcc and Reply-To headers from the message are still removed, so these two come only from the options. This changes behaviour for the to option combined with a ce-cc header: the to recipients now receive the email too.
  • contentType wins over the header. camel-mail prefers a Content-Type header to its contentType option. Many sources set that header: timer-source, for example, sets text/plain on every message, so the option alone had no effect in a Pipe from it (the Citrus test showed this). When contentType is set, the Kamelet removes the header. When it is not set, a Content-Type: text/html header still sends HTML, as before.
  • Trust store. No Kamelet option is needed. camel-mail uses the global SSL context when the component has useGlobalSslContextParameters. The descriptions and doc pages give the application properties: camel.ssl.enabled, camel.ssl.trustStore and camel.ssl.trustStorePassword, plus camel.component.imaps.useGlobalSslContextParameters=true for the sources, and camel.component.smtps... or camel.component.smtp... (with startTls) for the sink. JavaMail has no property for a trust store file. Its mail.imaps.ssl.trust turns off certificate checks for the listed hosts, so it is not used.
  • Left out: maxMessagesPerPoll. The Kamelets already have fetchSize (default 10), and camel-mail ignores maxMessagesPerPoll while fetchSize is set. Also left out: the date searches (searchTerm.fromSentDate and the like). The date pattern of camel-mail is yyyy-MM-dd HH:mm:SS, where SS is milliseconds, so a fixed date is read wrongly. The now-24h form can be added later if someone needs it.
  • Descriptions. The "Good to know" paragraphs say what happens to an email by default and when processing fails. The partial pages have a table of the outcomes, an example of the search options with moveTo, a mail-sink example with cc, bcc, replyTo and contentType, and the trust store properties.
  • Not in this PR. The subject and from options of mail-sink are still put into the URI without RAW(), so a + in them becomes a space: subject: "C++ build 100% done" arrives as C build 100% done. The to option does not have this problem any more, because it now goes through a header. This is left for a separate change, because it changes the endpoint URI of every mail-sink.
  • Citrus. mail-sink-route now also sets cc, bcc, replyTo and contentType: text/html, and checks Cc, Reply-To and the content type. The Citrus mail server does not show Bcc. MailIT passes.

Verification

Tested with Camel JBang 4.24.0-SNAPSHOT (camel run --local-kamelet-dir=kamelets) against GreenMail 2.1 (greenmail/standalone) with IMAP, IMAPS, SMTP and SMTPS. GreenMail had login on, and a server certificate for localhost and 127.0.0.1, signed by a test CA. For STARTTLS, which GreenMail's SMTP does not offer, I used Mailpit with --smtp-require-starttls. The sources trusted the test CA through camel.ssl.* with camel.component.imaps.useGlobalSslContextParameters=true. The mailboxes were checked over IMAP before and after each run. Each source case ran for several 2-second checks.

ms-exchange-online-imap-oauth-source needs a token from Microsoft, so it was not tested against Exchange Online. To test its template, the OAuth authenticator bean was replaced by camel-mail's DefaultAuthenticator, and everything else was kept, including mail.imaps.auth.mechanisms=XOAUTH2. GreenMail accepts XOAUTH2 and takes the token as the password. The real Kamelet with a made-up tenant fails to start, as on main (AADSTS90002: Tenant ... not found).

Case Result
Options unset, camel get endpoint, main and this branch: mail-imap-source, mail-sink, and the Exchange template Identical URIs
moveTo: Processed Email moved to Processed (created) and marked read; inbox empty
delete: true Email gone; no other folder
copyTo: Archive Email stays in the inbox, read; an unread copy is in Archive
delete: true + moveTo Moved; the copy is unread
Unset, inbox with one unread and one read email Only the unread one is read
unseen: false Both are read, and read again at every check
unseen: false + delete: true Both read once, then deleted
Processing fails, peek unset The email stays unread and is read again at every check. The next email in the inbox is still processed.
Processing fails, peek: true The same
Processing fails, peek: false Marked read at the first attempt, not read again
Processing fails with delete + copyTo, or with moveTo Not deleted, not copied, not moved; stays unread. The good email next to it is deleted or moved.
Broken email (Content-Transfer-Encoding: x-bogus-encoding) before a good one, unset Every check fails with Unknown encoding; the good email is never read
The same, skipFailedMessage: true The good email is read; the broken one stays unread, and nothing is logged
folderName: Orders Reads Orders only; the inbox email is untouched
folderName: "INBOX.Orders Returns+1 (x)", moveTo: "Done+1 (y)" Read and moved; names kept as written
folderName that does not exist A warning at every check; the integration keeps running
searchSubject: invoice Reads "Invoice 42"; skips "Other" and the already read "old invoice 7"
searchSubject: invoice + unseen: false Reads "Invoice 42" and "old invoice 7"; skips "Other"
searchFrom: BOB@EXAMPLE.COM Reads only the email from bob@example.com
searchTo: alice@example.com Reads the email to alice; skips the one where alice is only in Cc
searchSubjectOrBody: REFUND Reads "Hello" (body "please refund") and "Refund request"; skips "Other"
searchSubject: "A+B & C 100%" Reads "Order A+B & C 100%"; skips "Order A B"
searchFrom + searchSubject (Exchange template) Reads only the email that matches both
Doc example: folderName (INBOX.Suppliers, GreenMail's separator), searchFrom, searchSubject, moveTo Only the matching email of the subfolder is moved to Processed
Exchange template: moveTo + searchSubject + unseen: false; delete + copyTo; folderName; peek unset and false; skipFailedMessage; searchFrom + searchSubject Same results as mail-imap-source
IMAPS, no trust store (as on main) Every check fails: PKIX path building failed
IMAPS, trust store with another CA The same
IMAPS, trusted CA, server addressed by an IP address that is not in the certificate No subject alternative names matching IP address
Sink on main: to: alice and a ce-cc: bob header The email goes to bob only, with no To
Sink: to, cc, bcc, replyTo: support+x@example.com, contentType: text/html alice (To), bob (Cc) and carol (Bcc) receive it; Reply-To: support+x@example.com; text/html; carol's copy shows no Bcc header
The same with a ce-to: dave header To: dave; bob and carol still receive it
The same with a ce-cc: dave header To: alice, Cc: dave; carol still receives it
The same with a Content-Type: text/plain header Sent as text/html (the option wins)
The same with Bcc: dave and Reply-To: dave headers on the message dave receives nothing; Reply-To is from the option
No contentType, no header / Content-Type: text/html header text/plain / text/html, as on main
smtps with a trust store (camel.component.smtps.useGlobalSslContextParameters=true) Sent
smtps without it PKIX path building failed
smtps with the trust store, IP not in the certificate No subject alternative names matching IP address
smtp + startTls: true (Mailpit) with a trust store (camel.component.smtp.useGlobalSslContextParameters=true) Sent over STARTTLS; Mailpit shows To, Cc, Bcc and Reply-To as set
The same without the trust store Could not convert socket to TLS ... PKIX path building failed
Citrus MailIT (timer-source to mail-sink, with cc, bcc, replyTo, contentType) Passes

./mvnw clean verify -DskipTests and then ./mvnw clean verify passed from the root. Before building, the library copies of the three Kamelets were refreshed with ./mvnw -pl library/camel-kamelets resources:copy-resources@copy-resource-one. The build regenerated kamelets-index.json. MailIT was run with ./mvnw -pl tests/camel-kamelets-itest verify -Denable.integration.tests=Nothing -Dit.test=MailIT.

Claude Code on behalf of Claus Ibsen

🤖 Generated with Claude Code

…read, and mail-sink takes cc, bcc, replyTo and contentType (apache#3170)

mail-imap-source and ms-exchange-online-imap-oauth-source take
folderName, unseen, delete, moveTo, copyTo, peek, skipFailedMessage
and four search options: searchFrom, searchTo, searchSubject and
searchSubjectOrBody. The search options map to the component's
searchTerm.* parameters, so no bean is needed. With a search, the
component takes unseen from the search and not from the endpoint, so
unseen is passed to both. All new options are optional placeholders
without a default: when they are not set, the endpoint URI is the same
as before. Folder names and search texts go through RAW(), and the
folder options reject % and *, which IMAP reads as wildcards.

mail-sink takes cc, bcc, replyTo and contentType. The mail component
takes the recipients either all from the To, Cc and Bcc headers or,
when there is none, all from the options, so a ce-to or ce-cc header
dropped the to, cc and bcc options: with the to option and a ce-cc
header, the email went to the copy recipient only. The Kamelet now
puts the to, cc and bcc options into the headers, so that a ce-to or
ce-cc header replaces only its own option and bcc is always kept.
Bcc and Reply-To still cannot come from the message. When contentType
is set, it wins over a Content-Type header, which sources such as
timer-source set to text/plain on every message.

A trust store for a private certificate authority is set with the
camel.ssl application properties and
camel.component.imaps/smtps/smtp.useGlobalSslContextParameters; the
descriptions and the doc pages say how. maxMessagesPerPoll is left
out: the fetchSize option already limits the emails of each check,
and the component ignores maxMessagesPerPoll while fetchSize is set.

The mail-sink Citrus test now also checks cc, Reply-To and the
content type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@davsclaus
davsclaus force-pushed the ci-issue-3170-mail-options branch from fdf5301 to a32de76 Compare November 18, 2026 20:01
@davsclaus
davsclaus merged commit 6569942 into apache:main Nov 18, 2026
6 checks passed
@davsclaus
davsclaus deleted the ci-issue-3170-mail-options branch November 18, 2026 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant