feat(email): expose typed received delivery reports (#763)

Author: bbottema

modules/cli-module/src/main/resources/cli.data

@@ -0,0 +1,18 @@
+package org.simplejavamail.api.email;
+
+/** What the reporting mail server says happened to one recipient's delivery. This is not proof of authenticity or that the recipient read the email. */
+public enum DeliveryAction {
+
+	/** The server reports successful delivery. */
+	DELIVERED,
+	/** Delivery has not finished; the server may still be trying. */
+	DELAYED,
+	/** The server reports that it has stopped trying to deliver. */
+	FAILED,
+	/** The server passed the email onward without a final delivery report. */
+	RELAYED,
+	/** The recipient address expanded into other destinations, such as a mailing list. */
+	EXPANDED,
+	/** The action was missing, unrecognized or contradictory; inspect the report warnings. */
+	UNKNOWN
+}

modules/cli-module/src/main/resources/therapi.data

@@ -0,0 +1,31 @@
+package org.simplejavamail.api.email;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.simplejavamail.api.mailer.SmtpServerResponse;
+
+import java.io.Serializable;
+
+/**
+ * The reporting system's explanation of a delivery result, with its protocol format attached.
+ * For an interpretable SMTP reply, use the existing response API instead of splitting its text yourself.
+ * All explanation text remains untrusted and may contain personal information.
+ */
+public interface DeliveryDiagnostic extends Serializable {
+
+	/** The reported explanation format, commonly {@code smtp}. Other systems' diagnostic formats are preserved. */
+	@NotNull String getType();
+
+	/** The explanation without its type prefix. This is source text, not a log-safe message or an application instruction. */
+	@NotNull String getText();
+
+	/**
+	 * The SMTP reply when the diagnostic uses the SMTP format and contains a recognizable reply, otherwise {@code null}.
+	 * An unavailable SMTP view does not discard the original explanation. No reply or delivery status is inferred from human prose.
+	 */
+	@Nullable SmtpServerResponse getSmtpResponse();
+
+	/** Indicates whether an SMTP view is available without printing the reported type or explanation. */
+	@Override
+	@NotNull String toString();
+}

modules/core-module/src/main/java/org/simplejavamail/api/email/DeliveryAction.java

@@ -0,0 +1,35 @@
+package org.simplejavamail.api.email;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * Delivery feedback extracted from a received notification Email. Convert MIME/EML through the usual converter and read
+ * {@link Email#getDeliveryStatusReport()}; applications do not construct these snapshots.
+ *
+ * <p>These are the received server's claims, not authenticated proof, a read receipt or instructions to resend. Correlation and business decisions
+ * remain application-owned. A missing notification does not establish delivery. Optional facts are absent when missing or unusable; warnings explain
+ * malformed recognized reports without discarding their usable facts. Unambiguous formatting can be recovered with a warning; if optional
+ * report reading stops, completed facts remain available with an incomplete-extraction warning. Required message-content reads can still fail conversion.</p>
+ */
+public interface DeliveryStatusReport extends Serializable {
+
+	/** The original submission's envelope identifier, when reported. It is separate from Message-ID and is not matched to application records automatically. */
+	@Nullable String getEnvelopeId();
+
+	/** The reporting server and its naming format together, or {@code null} when missing or unusable. */
+	@Nullable ReportedMailServer getReportingServer();
+
+	/** Recipient reports in their received order, including duplicate occurrences. The returned list is immutable and never {@code null}. */
+	@NotNull List<RecipientDeliveryReport> getRecipients();
+
+	/** Human-readable parsing cautions, not machine-readable error codes or a protocol transcript. The returned list is immutable and never {@code null}. */
+	@NotNull List<String> getWarnings();
+
+	/** Summarizes recipient actions and warning counts without identifiers, addresses or diagnostic text. */
+	@Override
+	@NotNull String toString();
+}

modules/core-module/src/main/java/org/simplejavamail/api/email/DeliveryDiagnostic.java

@@ -227,6 +227,8 @@ public class Email implements Serializable {
 	 */
 	@Nullable
 	private final DeliveryStatusNotification deliveryStatusNotification;
+	@Nullable
+	private final DeliveryStatusReport deliveryStatusReport;
 	private final boolean tlsRequiredForOnwardDelivery;
 	/** @see EmailPopulatingBuilder#withSendingToAcceptedRecipients(boolean) */
 	@Nullable
@@ -343,6 +345,7 @@ public Email(@NotNull final EmailPopulatingBuilder builder) {
 		useReturnReceiptTo = builder.getUseReturnReceiptTo();
 		returnReceiptTo = builder.getReturnReceiptTo();
 		deliveryStatusNotification = builder.getDeliveryStatusNotification();
+		deliveryStatusReport = builder.getDeliveryStatusReport();
 		tlsRequiredForOnwardDelivery = builder.isTlsRequiredForOnwardDelivery();
 		sendingToAcceptedRecipients = builder.getSendingToAcceptedRecipients();
 		overrideReceivers = builder.getOverrideReceivers();
@@ -683,6 +686,22 @@ public boolean isTlsRequiredForOnwardDelivery() {
 	public Boolean getSendingToAcceptedRecipients() {
 		return sendingToAcceptedRecipients;
 	}
+
+	/**
+	 * Returns delivery feedback extracted from this Email's original notification, or {@code null} when no accessible outer delivery report was found.
+	 * For example, convert a received bounce with the usual MIME/EML converter, then inspect its recipients and envelope identifier here.
+	 *
+	 * <p>This immutable snapshot describes the source notification, not a changing delivery tracker on the Email originally sent. Copies retain it
+	 * even if their content is edited; new replies and forwards do not inherit it. The getter performs no parsing or I/O. Ordinary outgoing templates
+	 * do not supply it, and conversion back to MIME does not synthesize a delivery report from it.</p>
+	 *
+	 * <p>Received claims are not authenticated delivery proof or permission to retry. If protected content could not be opened, inspect the existing
+	 * protection results as well: {@code null} does not establish that encrypted content contains no report.</p>
+	 */
+	@Nullable
+	public DeliveryStatusReport getDeliveryStatusReport() {
+		return deliveryStatusReport;
+	}
 
 	/**
 	 * @see EmailStartingBuilder#forwarding(MimeMessage)

modules/core-module/src/main/java/org/simplejavamail/api/email/DeliveryStatusReport.java

@@ -1770,6 +1770,12 @@ EmailPopulatingBuilder encryptWithSmime(@NotNull Path pemPath, @Nullable @Cli.Op
 	@NotNull
 	OriginalSmimeDetails getOriginalSmimeDetails();
 
+	/**
+	 * @see Email#getDeliveryStatusReport()
+	 */
+	@Nullable
+	DeliveryStatusReport getDeliveryStatusReport();
+
 	/**
 	 * If the Email instance currently being built was the result of a conversion in which the source message was S/MIME
 	 * signed / encrypted, this field will contain the decrypted MimeMessage instance.

modules/core-module/src/main/java/org/simplejavamail/api/email/Email.java

@@ -0,0 +1,35 @@
+package org.simplejavamail.api.email;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.io.Serializable;
+
+/**
+ * A delivery status such as {@code 5.1.1}, already checked and split into its three numeric parts.
+ * The status class has three possible values; unfamiliar subject/detail combinations remain readable rather than being discarded.
+ * Read the recipient's {@link DeliveryAction} too: a temporary problem can end in either delay or abandoned delivery.
+ */
+public interface EnhancedStatusCode extends Serializable {
+
+	/** The broad result: {@code 2} for success, {@code 4} for temporary failure or {@code 5} for permanent failure. */
+	int getStatusClass();
+
+	/** The middle part, from zero through 999, describing the area of the problem. For {@code 5.1.1}, this is {@code 1}. */
+	int getSubject();
+
+	/** The final part, from zero through 999, describing the particular condition within that area. */
+	int getDetail();
+
+	/** Whether the code belongs to the success class. This is a reported result, not independently verified delivery. */
+	boolean isSuccess();
+
+	/** Whether the code describes a temporary problem. This alone is not permission for the application to resend. */
+	boolean isTemporaryFailure();
+
+	/** Whether the code describes a permanent problem with sending the message in its current form. */
+	boolean isPermanentFailure();
+
+	/** The complete code, such as {@code 5.1.1}, with no diagnostic prose. */
+	@Override
+	@NotNull String toString();
+}

modules/core-module/src/main/java/org/simplejavamail/api/email/EmailPopulatingBuilder.java

@@ -101,6 +101,9 @@ public static boolean equalsEmail(final Email email1, final Email email2) {
         if (!fieldIsEqual(email1.getDeliveryStatusNotification(), email2.getDeliveryStatusNotification(), "deliveryStatusNotification")) {
             return false;
         }
+        if (!fieldIsEqual(email1.getDeliveryStatusReport(), email2.getDeliveryStatusReport(), "deliveryStatusReport")) {
+            return false;
+        }
         if (!fieldIsEqual(email1.getSendingToAcceptedRecipients(), email2.getSendingToAcceptedRecipients(), "sendingToAcceptedRecipients")) {
             return false;
         }

modules/core-module/src/main/java/org/simplejavamail/api/email/EnhancedStatusCode.java

@@ -175,6 +175,13 @@ public interface ExactEmailBuilder {
 	@Nullable
 	Boolean getSendingToAcceptedRecipients();
 
+	/**
+	 * Returns any clear delivery report parsed from the authoritative EML. This does not decrypt or rewrite the original message.
+	 * @see Email#getDeliveryStatusReport()
+	 */
+	@Nullable
+	DeliveryStatusReport getDeliveryStatusReport();
+
 	/**
 	 * Builds an {@link Email} whose existing getters expose the parsed EML fields while the original bytes remain authoritative for conversion,
 	 * rehearsal, and sending. At least one explicit envelope recipient is required.