You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 17847b4
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/API_EXPANSION_WORKFLOW.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -120,11 +120,14 @@ Implement the new API methods and ensure data propagation.
120
120
-**Update Email Constructor**: Ensure the `Email` constructor copies the new field from the builder.
121
121
-**Utility Classes**: Update `MiscUtil` if it contains helper methods for object creation or parsing (e.g., `interpretRecipient`).
122
122
-**Send Results**: Runtime facts belong to the send result, not the reusable Email. Preserve added fields through result enrichment, receipt construction, and serialization/read-resolution. Keep internal assembly out of the application API and use builders instead of adding positional constructor overloads. Review genuinely released construction contracts separately; retaining serialized compatibility does not require retaining unreleased constructors. Test absence behavior within the supported snapshot format. ADR 0031 explicitly supersedes compatibility with the former concrete report classes; keep that migration boundary distinct from the preserved Email/recipient/attachment format.
123
+
-**Interpreted Source Facts**: Facts extracted from a received message belong to its converted Email read model, not outgoing configuration or a live send result. See [ADR 0008](adr/0008-minimal-mime-structures-and-protection-order.md). Use core read contracts and internal assembly; preserve source metadata through copying/governance/serialization without letting templates manufacture it. Do not add setters, EmailProperty entries, defaults, locks, properties or CLI options for read-only facts. Verify the effective outer message after protection processing, exact/protected bytes, attached-message isolation and absence in older snapshots.
Route the new field according to its ownership. Message-content fields affect the produced `MimeMessage`; SMTP-envelope fields belong to `DeliveryEnvelope` and the provider adapter, not MIME headers. Do not change exact or protected MIME bytes to carry transport metadata.
127
128
129
+
-**Read Tolerantly, Produce Strictly**: Follow [ADR 0035](adr/0035-tolerant-reading-and-strict-production.md) for MIME/EML/Outlook imports and interpreted source facts. Recover unambiguous formatting, preserve usable neighboring facts and source data, and explain incomplete interpretation through existing feature metadata. Do not make an optional interpretation reject an otherwise readable Email. Keep conflicting or genuinely ambiguous facts unavailable; never invent dates, timezones, recipients or delivery results. Required content-read failures retain their causes rather than returning complete-looking truncated content. Add malformed/partial-source regressions alongside valid fixtures, and preserve outgoing validation, exact/protected bytes and cryptographic verification.
130
+
128
131
-**MimeMessageHelper**: Update this class if the new field translates directly to a standard MimeMessage header or property (e.g., a new recipient type or a standard header).
129
132
-**SpecializedMimeMessageProducer**: Update the `populateMimeMessage` method if the new field requires logic to decide how the `MimeMessage` is constructed or if it triggers module-specific processing (like S/MIME or DKIM).
130
133
-**MIME Structure**: For a new body-part concept, revisit the mixed/related/alternative selector and each affected producer. [ADR 0008](adr/0008-minimal-mime-structures-and-protection-order.md#mime-producer-selection) contains the producer matrix and protection-order contract; retain custom Message-ID behavior across wrappers.
Copy file name to clipboardExpand all lines: docs/adr/0008-minimal-mime-structures-and-protection-order.md
+52Lines changed: 52 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,6 +61,58 @@ Simple messages stay simple and clients see multipart containers that correspond
61
61
62
62
Security and conversion must preserve Message-ID and exact protected bytes across repeated serialization. Missing optional modules must not silently downgrade requested outbound protection. On incoming mail, accessible content and unavailable verification/decryption facts remain distinct; successful parsing alone is not evidence of trust. Exact EML bypasses this composition pipeline and uses its own preservation contract.
63
63
64
+
## Interpreted mail facts remain part of Email (accepted 2026-10-16)
65
+
66
+
This addendum is implemented under [#763](https://github.com/bbottema/simple-java-mail/issues/763), verified and accepted in production review on 2026-10-18;
67
+
the earlier MIME/protection decisions remain implemented. The independent integration programme is [#764](https://github.com/bbottema/simple-java-mail/issues/764).
68
+
69
+
### Context and decision drivers
70
+
71
+
An application already converts MIME/EML into Email to inspect bodies, addresses and protection results. Delivery-status notifications are specialized
72
+
mail content, not a second transport outcome. Exposing their interpreted facts through another converter facade would fragment the gateway without
73
+
changing who owns the content. Turning those facts into workflow transitions, however, requires application-specific persistence, trust and business rules.
74
+
75
+
### Decision
76
+
77
+
Enrich the common Email read model with immutable source facts during existing inbound conversion. Apply the established protection-before-interpretation
78
+
order: inspect the effective outer notification, retain authoritative protected/exact bytes and do not promote an attached report into its parent's facts.
79
+
Keep source metadata separate from outgoing configuration, SMTP submission results and application state. Ordinary templates, locks and outbound MIME
80
+
producers must not manufacture source facts. Copies preserve provenance, while new replies/forwards describe their own source rather than their subject.
81
+
82
+
Core owns the reading contracts; the main conversion implementation owns parsing and assembly. Reuse Jakarta Mail's MIME/header machinery without an
83
+
optional experimental DSN dependency. Missing/unusable facts remain absent; a recognized malformed notification can retain usable facts and warnings.
84
+
[ADR 0035](0035-tolerant-reading-and-strict-production.md) makes the inbound tolerance boundary explicit: recover unambiguous formatting and retain
85
+
completed facts when optional interpretation fails, with warnings. Failure to obtain required content still fails conversion rather than returning
86
+
silently truncated content. Received claims are not authenticated delivery proof or permission to retry.
87
+
88
+
Use cohesive read types for interpreted values rather than leaving applications to split status strings or keep parallel type/value getters aligned.
89
+
An enhanced status exposes checked numeric components and broad classification while preserving unfamiliar subject/detail combinations. Reported
90
+
addresses, servers and diagnostics retain their extensible format identifiers alongside their values; only recognized usable formats offer optional
91
+
Internet-mailbox or SMTP-response views. Those conveniences must not invent absent names, outgoing preferences or delivery evidence. Their construction
92
+
stays internal to conversion, and automatic rendering excludes reported identities and prose.
93
+
94
+
### Alternatives considered
95
+
96
+
-**A parallel delivery-report extractor API:** explicit, but forces callers to select another gateway for facts that belong to the converted Email.
97
+
-**Application-only raw parsing:** avoids library work but duplicates mail-format/protection knowledge across integrations.
98
+
-**An SJM handler registry, dispatcher or durable workflow:** convenient for one example, but makes mail interpretation own application persistence,
99
+
scheduling, correlation and business state. Teach those integrations instead, using their existing platforms.
100
+
101
+
### Consequences and boundaries
102
+
103
+
Specialized interpretation is discoverable through the same Email object, without getter-side I/O or new configuration layers. It does not turn Email
104
+
into a mutable delivery tracker. Callers choose correlation, trust, serialization, logging and downstream action; no missing-report success inference or
105
+
automatic retry follows. Metadata must survive copying and supported serialization without retaining MIME objects or changing wire bytes.
and [public/internal boundaries](0031-public-api-and-internal-construction.md). Acceptance tests and feature contracts belong in the implementation plan,
110
+
not this decision record. Sending ownership, state machines and the shared concurrency infographic's resource layers remain unchanged.
implements interpreted notification facts within the shared MIME pass. [DeliveryStatusReportTest](../../modules/simple-java-mail/src/test/java/org/simplejavamail/converter/DeliveryStatusReportTest.java)
116
+
and the [dated verification record](../research/763-delivery-status-verification.md) cover this extension separately from the historical evidence below.
117
+
66
118
[MimeMessageProducerHelper](../../modules/simple-java-mail/src/main/java/org/simplejavamail/converter/internal/mimemessage/MimeMessageProducerHelper.java), [SpecializedMimeMessageProducer](../../modules/simple-java-mail/src/main/java/org/simplejavamail/converter/internal/mimemessage/SpecializedMimeMessageProducer.java), [builder validation](../../modules/simple-java-mail/src/main/java/org/simplejavamail/email/internal/EmailPopulatingBuilderImpl.java), and [EmailConverter](../../modules/simple-java-mail/src/main/java/org/simplejavamail/converter/EmailConverter.java) implement these boundaries. [OpenPgpMimeTest](../../modules/simple-java-mail/src/test/java/org/simplejavamail/openpgp/OpenPgpMimeTest.java) and [OpenSSL S/MIME interoperability tests](../../modules/simple-java-mail/src/test/java/org/simplejavamail/internal/smimesupport/OpenSslSmimeInteroperabilityTest.java) are existing verification anchors, not newly executed tests for this record.
Copy file name to clipboardExpand all lines: docs/adr/0011-transport-neutral-submission-outcomes.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -79,4 +79,8 @@ Absence of a receipt must never be interpreted as proof that no message was acce
79
79
80
80
Recipients and raw server replies can contain personal information and untrusted text; they are not redacted configuration diagnostics. SMTP acceptance is not mailbox delivery. DSNs, bounces and application reconciliation remain separate concerns. Pending ENVID work adds correlation metadata but does not change these meanings.
adds reading of a supplied delivery notification through its converted Email. This is distinct from the original send result: a received report does
84
+
not mutate a receipt, authenticate delivery or authorize automatic replay. Mail retrieval, correlation and business reconciliation remain application-owned.
85
+
82
86
Existing regression landmarks include [AngusSubmissionResultTest](../../modules/angus-mail-provider-module/src/test/java/org/simplejavamail/internal/mailprovider/angus/AngusSubmissionResultTest.java) and [MailSubmissionReceiptTest](../../modules/simple-java-mail/src/test/java/org/simplejavamail/mailer/MailSubmissionReceiptTest.java). This retrospective documentation pass did not rerun Java tests.
Copy file name to clipboardExpand all lines: docs/adr/0013-exact-eml-submission.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,6 +18,9 @@ Keep `Email` as the public message type. `startingFromExactEml(...)` returns a c
18
18
19
19
Make the input bytes the sole authority for MIME content. The parsed Email getters are an inspection view; they are not the recipe used to reconstruct the message. Internally, `InternalEmail` owns an `EmailSource`: composed sources apply governance and render MIME, while `ExactEmlSource` returns a `FinalizedMimeMessage` from copied bytes and declares `PRESERVE_ALL_BYTES`. Keep this distinction at the source boundary rather than scattering exact/composed checks through every send mode.
20
20
21
+
[ADR 0035](0035-tolerant-reading-and-strict-production.md) permits recovery in that inspection view without changing authoritative bytes.
22
+
Tolerant reading does not relax this explicit submission mode's validation, content-preservation or transport-safety requirements.
23
+
21
24
Exact submission bypasses Email defaults/overrides, composed-message validation, embedded-resource resolution and DKIM/S/MIME/OpenPGP transformations. Content that is already final must not silently acquire headers, signatures or encryption. Envelope invariants and the configured maximum byte size still apply. Copying an exact Email through the ordinary composition builder intentionally creates a composed source and relinquishes the preservation contract.
22
25
23
26
[ADR 0028](0028-per-email-recipient-rejection-handling.md) records the explicit recipient-rejection choice on ExactEmailBuilder under #754.
0 commit comments