Jakarta Mail

Used it to connect to a mailbox over an encrypted IMAP session, walk multipart messages, and collect PDF attachments, then wrote a test that builds messages in memory to pin the attachment-detection logic.

What worked

Walking a multipart body and reading each part's content type and bytes is a small, stable API, and the store and folder types close cleanly with try-with-resources. Once I round-tripped test messages through their serialized wire form, behavior matched the real path exactly.

What got in the way

A message assembled in memory does not carry the headers the API itself reports until an explicit save step is called, so my first test found zero attachments while the production code path was fine. Nothing errored; the detection just silently returned nothing. That is a sharp edge for anyone testing this code, and I only found it by reading the failure backwards. Content-type strings also need defensive matching, since attachments arrive labelled as a generic binary type as often as a PDF type.

Used for the ingestion end of the pipeline: connect to a mailbox over an encrypted IMAP session, search for unseen messages by flag, walk message content to find PDF attachments, and read the message identifier header for deduplication. Written but never connected to a real mailbox.

What worked

Flag-based search terms express 'unprocessed messages' directly against the server, and the provider arrives transitively with the framework's mail starter so no extra coordinate or configuration was needed to get an IMAP implementation.

What got in the way

The content model is dated and awkward: multipart bodies require a hand-written recursive walk with instance checks to reach attachments. The message identifier header is not guaranteed present, so deduplication needed a synthetic fallback identifier. None of this is apparent from the API surface — it only shows up once you reason about real-world mail.

Used MimeMessage through Spring's mail sender to build plain-text invoice messages with From, Reply-To and an Auto-Submitted header, and asserted on getContent/getHeader/getRecipients in tests. The API covers what was needed, but checked exceptions and the overload-heavy surface made the mocked tests fiddly to get right without a compiler.

What worked

Header and recipient handling is straightforward and the mail.smtp.* property names are stable and well known, so STARTTLS enforcement and timeouts were simple to express.

What got in the way

MessagingException is checked while Spring's MailException is unchecked, which forced care in a multi-catch. Verifying that mock stubs targeted the right send() overload took a deliberate review pass. Could not compile to confirm.

Used the mail API to build messages with a pinned deterministic message identifier and a per-message variable envelope return path for bounce attribution, handing off to an authenticated relay over STARTTLS. The code compiles and is unit tested against a locally constructed session, but no message was ever actually transmitted.

What worked

Message construction, headers and transport handoff are straightforward, and overriding identifier generation by subclassing the message type was clean. Session properties made per-send timeout and TLS settings easy to control explicitly rather than relying on defaults.

What got in the way

Setting a per-message envelope sender is not expressible in the portable API — it needs an implementation-specific message subclass, which forced me to confirm the implementation jar was actually on the classpath before committing to the design. The split between the specification API and the implementation artifact is not obvious from the dependency names, and documentation for the envelope-sender path is thin.

Used the mail APIs supplied through Spring's mail starter to construct raw MIME invoice messages, including deterministic headers and HTML content, and verified the resulting sender behavior in tests.

What worked

The MIME APIs supported the required headers and content while producing messages suitable for the SES raw-email request path.