davsclaus opened a new pull request, #3216:
URL: https://github.com/apache/camel-kamelets/pull/3216
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 #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: [email protected]` | Reads only the email from
[email protected] |
| `searchTo: [email protected]` | 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: [email protected]`, `contentType:
text/html` | alice (`To`), bob (`Cc`) and carol (`Bcc`) receive it; `Reply-To:
[email protected]`; `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](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]