Skip to content

Commit 6e796f8

Browse files
committed
docs(delivery-reports): document feedback and competitive progress (#763)
1 parent 17847b4 commit 6e796f8

3 files changed

Lines changed: 25 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ application-global instance for Mailers from the configured factory. Your applic
1515
the library records logical sends and actual submission attempts without depending on observer delivery. Endpoint attributes are opt-in.
1616
See [OpenTelemetry setup, privacy and illustrative output](https://www.simplejavamail.org/opentelemetry.html).
1717

18+
For received delivery notifications, use the ordinary MIME/EML converter and inspect `notificationEmail.getDeliveryStatusReport()`.
19+
Its recipient reports expose checked status-code components, reported addresses with optional `Recipient` views, and diagnostics with optional
20+
`SmtpServerResponse` views. Unknown formats remain readable without asking application code to split protocol strings.
21+
It exposes correlation and recipient facts without turning the notification into an instruction to resend.
22+
See [Reading delivery reports](https://www.simplejavamail.org/delivery-reports.html).
23+
1824
Jakarta Mail provides the standard mail API, and Angus Mail provides its transport implementation. You can still supply a `Session`, access the generated `MimeMessage`, set raw Jakarta Mail properties, or provide the final send operation.
1925

2026
[Get started](https://www.simplejavamail.org/download.html) · [Capabilities](https://www.simplejavamail.org/features.html) · [Modules](https://www.simplejavamail.org/modules.html) · [Javadocs](https://javadoc.io/doc/org.simplejavamail/maven-master-project) · [9.2 migration guide](https://www.simplejavamail.org/migration-notes-9.2.0.html) · [Compare libraries](https://www.simplejavamail.org/feature-matrix.html)

‎RELEASE_HISTORY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ Full Simple Java Mail release history. The [README](https://github.com/bbottema/
66

77
### Major Features
88

9+
- [#763](https://github.com/bbottema/simple-java-mail/issues/763): expose structured delivery-status reports through the converted notification Email, with ordered recipient actions, strongly typed status codes, reported recipients/servers, diagnostics, correlation facts and parsing warnings. Internet-mailbox and SMTP-response views are available when interpretable. Existing MIME/protection conversion remains the gateway; reports are received claims, not final-delivery proof or automatic retry instructions.
10+
911
- [#762](https://github.com/bbottema/simple-java-mail/issues/762): added explicit optional OpenTelemetry integration for logical-send and provider-invocation spans, sampling-independent metrics and portable phase measurements. Applications supply and own their SDK; privacy-safe defaults exclude endpoints unless permitted, and telemetry stays independent of progress/result callbacks.
1012

1113
- [#760](https://github.com/bbottema/simple-java-mail/issues/760): added optional live mail-send progress beside the terminal result observer, with bounded non-blocking reporting, logical-send observation IDs, retry-aware stages and managed Angus upload counts. Progress is best-effort; receipts and final results remain authoritative. Renamed the unreleased terminal callback to `MailSendResultObserver` to distinguish the two registrations.

‎docs/research/simple-java-mail-world-class-smtp-progress-report.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
# Simple Java Mail 10.0.0 competitive progress report
22

3-
- Assessment date: 2026-10-16.
3+
- Assessment date: 2026-10-18.
44
- Implementation refresh: 2026-10-15, adding accepted live progress under [#760](https://github.com/bbottema/simple-java-mail/issues/760), detailed connection/SMTP stages under [#761](https://github.com/bbottema/simple-java-mail/issues/761), retention corrections and a repeatable memory-pressure workbench. Safe retries under #756, connection failover under #755, selected-Mailer ownership corrections under #757 and earlier recipient-rejection/managed-transport updates remain part of the assessment.
55
- Optional OpenTelemetry [#762](https://github.com/bbottema/simple-java-mail/issues/762) is implemented and accepted after production-only and holistic review on 2026-10-16. This is development-branch work for 10.0.0, not a released capability.
6+
- Incoming delivery-status interpretation [#763](https://github.com/bbottema/simple-java-mail/issues/763) is implemented, verified and accepted in production review on 2026-10-18. The [delivery-report verification](763-delivery-status-verification.md) records typed facts, tolerant recovery and preserved source/security boundaries.
67
- Competitor baseline: 2026-10-04. Symfony failover, Nodemailer pooling, MailKit SMTP capabilities and Vert.x PIPELINING documentation were rechecked on 2026-10-12 for this refresh; the wider comparison was not repeated.
78
- Original research: [The World-Class SMTP Framework](simple-java-mail-world-class-smtp-research.pdf), dated 2026-08-29.
8-
- Implementation baseline: [`e0fd0ac6`](https://github.com/bbottema/simple-java-mail/commit/e0fd0ac62394a652d2d617ba08e6ed9311436b0a) on `codex/10.0.0`, containing accepted #762 telemetry runtime/configuration integration on top of reviewed #760/#761 progress, retention corrections and the memory workbench, following the earlier retries and failover delivery. The implementation and evidence records linked below identify the reviewed scope.
9+
- Implementation baseline: [`53eeb9ab`](https://github.com/bbottema/simple-java-mail/commit/53eeb9ab) on `codex/10.0.0`, adding accepted #763 typed delivery-report interpretation and tolerant reading to the earlier telemetry, live progress, retries and failover work. The implementation and evidence records linked below identify the reviewed scope.
910
- Release status: development of 10.0.0 continues. The assessed capabilities are present on the development branch, not in a published release. This does not describe the capabilities of the published 9.x libraries.
10-
- Method: repository and recorded verification review, including the #756, #760, #761 and #762 verification sequences. Competitor documentation was not re-researched for the 2026-10-16 telemetry refresh; those comparisons retain their recorded dates. No cross-library benchmark or new competitive black-box comparison was run.
11+
- Method: repository and recorded verification review, including the #756, #760, #761, #762 and #763 verification sequences. Competitor documentation was not re-researched for the 2026-10-18 delivery-report refresh; those comparisons retain their recorded dates. No cross-library benchmark or new competitive black-box comparison was run.
1112

1213
This is the companion to the original PDF. Keep the two together: the PDF records the initial comparison and research agenda; this report explains what has changed, where Simple Java Mail now compares well, and where the original gaps remain. Its comparisons are assessments, not independently measured rankings.
1314

@@ -45,6 +46,7 @@ The PDF described a broad and approachable library with important operational an
4546
| Configuration and integration | Immutable snapshots, redacted value provenance, Spring/Boot integration, and factory-scoped configuration locks. | [#715](https://github.com/bbottema/simple-java-mail/issues/715), [#714](https://github.com/bbottema/simple-java-mail/issues/714), [#740](https://github.com/bbottema/simple-java-mail/issues/740) |
4647
| Operating a mail workload | Measurements of actual sends, configurable message/recipient sending limits, and internal content-inspection/provider-discovery optimizations. | [#750](https://github.com/bbottema/simple-java-mail/issues/750), [#751](https://github.com/bbottema/simple-java-mail/issues/751), [#749](https://github.com/bbottema/simple-java-mail/issues/749) |
4748
| Optional application telemetry | Typed adaptation of the application's SDK, ordinary Mailer/property configuration, request-linked logical/invocation spans, portable phase timings/failure location, useful duration histograms and sampling-independent metrics. Accepted for unreleased 10.0.0, with private-by-default endpoint reporting. | [#762](https://github.com/bbottema/simple-java-mail/issues/762) |
49+
| Incoming delivery feedback | Structured DSN facts through the ordinary converted Email: ENVID, ordered recipient actions, checked status-code components, reported recipients/servers, typed diagnostics and dates. Optional mailbox/SMTP views avoid caller-side parsing without losing unfamiliar formats. Tolerant reading recovers clear formatting defects and retains completed facts after optional extraction fails, with warnings; ambiguous facts remain unavailable. Applications retain trust, correlation and business decisions. | [#763](https://github.com/bbottema/simple-java-mail/issues/763) |
4850

4951
These capabilities work together. An application can configure and rehearse mail, submit it through managed resources, inspect what SMTP accepted, and decide what to do after a failure without treating every exception as proof that nothing was sent.
5052

@@ -130,6 +132,18 @@ Users can express their service's restrictions as counts over periods instead of
130132

131133
These count local attempted provider submissions. They do not establish account-wide quota compliance across processes, persistent history, server-observed arrival timing or final delivery. See [ADR 0027](../adr/0027-factory-scoped-sending-limits.md) and the [verification record](sending-limits-verification.md).
132134

135+
### Received delivery feedback
136+
137+
The accepted #763 feature closes the gap between SMTP submission evidence and later machine-readable delivery feedback. A converted incoming Email
138+
exposes its own immutable delivery-status report, without a second parsing entry point or application code that walks MIME/header blocks. The same
139+
Email gateway already used for content and protection now supplies typed notification facts. It does not retroactively change the originally sent
140+
Email or claim to be a receiving service, authenticated delivery proof, mailbox monitor or read-receipt tracker.
141+
142+
Competitively, this extends the existing construction/submission/diagnostics gateway into received delivery feedback, including typed conveniences and
143+
tolerant recovery of imperfect notifications. DSN parsing itself is not unique to SJM. The advantage is the integrated Email API and preservation of
144+
content/security boundaries, without requiring applications to assemble a separate parsing pipeline. No competitor research or cross-library
145+
measurements were repeated for this addition; PIPELINING/CHUNKING remains a separate protocol track.
146+
133147
### Per-email recipient rejection handling
134148

135149
Applications can now choose what a recipient rejection means for that email without finding a provider-specific property. If Alice and Bob are

0 commit comments

Comments
 (0)