Class MailFailure

java.lang.Object
com.iizix.mail.MailFailure

public final class MailFailure extends Object
What a failed send of a queued mail means for its queue (CC-FIX-MAIL-PERMANENT-FAILURE): a failure that will always fail is not tried again.

PERMANENT: the relay answered a 5xx reply - to RCPT (the address refused: 550, 553, 501, 551, 503 and every other 5xx but 552, which JavaMail itself reads as a quota, a temporary condition), to MAIL FROM (the sender address refused) or to DATA - or an address of the mail cannot be parsed. A mail with several recipients of which the relay refused SOME for good and accepted the others is permanent as well: it was delivered to the accepted ones (mail.smtp.sendpartial, set by MailSender), the refused ones are reported, and nothing is left to try.

TRANSIENT: a 4xx reply, a connection or read failure, the relay unreachable, a dropped connection, an authentication failure (the configuration is fixed by the operator and the mail then goes), anything else. The recipients the relay accepted meanwhile are in getAccepted(): a retry goes to getUnsent() only, never a second copy to them.

Author:
Christopher Mindus
  • Method Details

    • of

      public static MailFailure of(MessagingException e)
      Classifies a failed send, see the class comment.
      Parameters:
      e - The failure, as Transport.sendMessage or the message's address parsing threw it.
      Returns:
      The classification.
    • isPermanent

      public boolean isPermanent()
      Checks if the failure is permanent: the mail is not tried again.
      Returns:
      true for a permanent failure, false for a transient one.
    • getCode

      public int getCode()
      Gets the reply code of the deciding reply.
      Returns:
      The three-digit code, zero when no reply was read (a connection failure).
    • getStatus

      public String getStatus()
      Gets the enhanced status of the deciding reply.
      Returns:
      The status, e.g. "5.1.4", null when the reply carries none or no reply was read.
    • getReply

      public String getReply()
      Gets the deciding reply as the relay sent it.
      Returns:
      The reply line, null when no reply was read.
    • getRefused

      public Address[] getRefused()
      Gets the recipients the relay refused for good.
      Returns:
      The refused recipients, empty for none.
    • getAccepted

      public Address[] getAccepted()
      Gets the recipients the relay accepted the mail for in the failed attempt.
      Returns:
      The accepted recipients, empty for none.
    • getUnsent

      public Address[] getUnsent()
      Gets the recipients the mail was not sent to and that may still take it.
      Returns:
      The recipients still to send to, empty for none.
    • getCause

      public MessagingException getCause()
      Gets the failure.
      Returns:
      The failure.
    • describe

      public String describe()
      Describes the failure in one line for the log, with every address masked (EmailAddressForm.masked(String)): the relay's reply, or the one-line form of the failure when no reply was read; the refused recipients; the recipients accepted meanwhile.
      Returns:
      The one line, without a stack trace.
    • masked

      public static String masked(String text)
      Masks every address in a text for a log line (EmailAddressForm.masked(String)): the text of a failure can carry an address, echoed by the relay in its reply or named by JavaMail in its message.
      Parameters:
      text - The text, null for none.
      Returns:
      The text with every address masked, "null" for null.
    • toString

      public String toString()
      Overrides:
      toString in class Object