Skip to content

Expose per-recipient SMTP replies and retry guidance #723

Description

@bbottema

Part of #722, phase 1 of 03_SMTP_ROBUSTNESS_IMPROVEMENT_PLAN. Extends the unreleased submission-result API from #710.

Why

A failed send does not necessarily mean that no mail was accepted. Mixed recipients can receive different SMTP replies, and losing the final DATA reply leaves acceptance uncertain. Applications need those facts to decide whether to retry the whole message, retry particular recipients, or ask for human review.

Angus also deliberately throws reporting exceptions when mail.smtp.reportsuccess=true, even after complete acceptance. Simple Java Mail currently misclassifies that successful transaction; this phase corrects it.

Scope

  • Add immutable recipient results in envelope order, with original/mailbox addresses, final submission disposition, RCPT-attempt knowledge, the observed primary reply and text, and an optional enhanced status.
  • Retain existing accepted, valid-unsent and invalid recipient getters as immutable compatibility views.
  • Derive conservative transaction-level retry guidance and a known-retryable recipient list. Never resend automatically or imply exactly-once delivery.
  • Extract provider exception types structurally; normalize genuine success-reporting exceptions only when the whole transaction was accepted.
  • Keep original provider failures, missing replies, unknown final acceptance, custom mailers and third-party adapters intact.
  • Keep captured facts local to one attempt, including pooled async sends, simple batches, open connections and observers.

Acceptance

  • All-success reporting mode returns success.
  • Mixed 2xx/4xx/5xx RCPT results, final rejection and final-reply loss remain distinct.
  • Enhanced-status parsing rejects malformed or conflicting status text.
  • Ordered recipient results agree with compatibility views and remain immutable.
  • Retry guidance excludes permanent rejection and flags duplicate risk.
  • Actual pooled SMTP tests cover concurrency, reuse, invalidation and recovery.
  • Classpath/JPMS consumers and incomplete third-party provider results remain supported.
  • Existing submission-result documentation explains the API and its limits.

Only this phase is being implemented. Later phases and benchmarking are out of scope. Leave the changes available for review before commit and closure.

Implementation is ready for review on the 10.0 branches; it has not been committed or released.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions