v2.0.0

Breaking Changes

• By default, Email#normalized now lowercases the email address and removes any extraneous quotes in
  the local-part of the address. To revert this behavior so that it behaves the same as v1, use the following:

  myEmailObject.normalized(
    NormalizationOptions.builder()
      .keepQuotes()
      .adjustCase(CaseOption.NO_CHANGE)
      .build());
  

• The jmail.normalize.strip.quotes JVM system property no longer does anything. Quotes are stripped by default now.
  If you need to disable quote stripping, use NormalizationOptionsBuilder#keepQuotes().

• Removed Email#normalized(boolean) method which allowed for a normalized email with stripped quotes.
  Quotes are stripped by default now. If you need to disable quote stripping, use NormalizationOptionsBuilder#keepQuotes().

• FailureReason was switched from an enum to a class in order to support custom failure reasons, so it is no longer
  possible to use it in a switch statement.

• Email addresses that fail validation due to additional rules added to the EmailValidator (such as
  disallowIpDomain() or requireValidMXRecord()) no longer return a generic FailureReason.FAILED_CUSTOM_VALIDATION
  in the EmailValidationResult. Instead, it returns a more specific FailureReason depending on the rule.

• FailureReason.MISSING_TOP_LEVEL_DOMAIN was changed to FailureReason.MISSING_FINAL_DOMAIN_PART.
  MISSING_TOP_LEVEL_DOMAIN was previously used for email addresses that failed validation because
  they ended the email address with a comment. This FailureReason was potentially misleading, for example if you
  enabled requireTopLevelDomain() on your EmailValidator. Note that the MISSING_TOP_LEVEL_DOMAIN failure reason
  is now used properly: if you use the rule requireTopLevelDomain(), any address that is missing the TLD will give
  that failure reason.

FailureReason Improvements

Changes to the FailureReason supplied for additional rules

The FailureReason returned in the EmailValidationResult is useful to understand why a specific
email address failed validation. In v2.0.0, the FailureReason returned for email addresses that failed
one of the additional validation rules added to your EmailValidator (such as disallowIpDomain() or
requireValidMXRecord()) now return more specific and useful reasons (such as CONTAINS_IP_DOMAIN or
INVALID_MX_RECORD).

EmailValidator validator = JMail.strictValidator()
  .requireOnlyTopLevelDomains(TopLevelDomain.DOT_COM);
  
EmailValidationResult result = validator.validate("[email protected]");

assertEquals(FailureReason.INVALID_TOP_LEVEL_DOMAIN, result.getFailureReason());

Option to provide FailureReason for custom rules

Additionally, you can specify your own FailureReason for any custom validation rules that you add
to your EmailValidator. Use the new withRule(Predicate<Email>, FailureReason) or
withRules(Map<Predicate<Email>, FailureReason>) methods to specify the failure reason for each
of your custom rules. If no failure reason is supplied, then the rule will default to the
FailureReason.FAILED_CUSTOM_VALIDATION reason.

FailureReason nonGmailFailure = new FailureReason("NON_GMAIL_ADDRESS");

EmailValidator validator = JMail.strictValidator()
  .withRule(e -> e.domain.startsWith("gmail"), nonGmailFailure);
  
EmailValidationResult result = validator.validate("[email protected]");

assertEquals(nonGmailFailure, result.getFailureReason());

Email Address Normalization Improvements

New Normalization Methods

This version introduces a new NormalizationOptions class that is used to provide
configuration of the behavior of the Email#normalized() method. See the table below to see
all the new and existing options.

In v2.0.0, you can use either Email#normalized() (with no parameters) or Email#normalized(NormalizationOptions options).

The first method without parameters will return a normalized email address based on the default
normalization options. The second method allows you to provide your own NormalizationOptions at runtime
depending on your needs. The custom normalization options can be created using the NormalizationOptions#builder()
method.

Normalization Options

Thanks, @Sprokof, for contributing (introducing removeDots and adjustCase options)! 🎉

Option	Description	NormalizationOptionsBuilder Method
stripQuotes	Remove all unnecessary quotes in the local-part of the address	stripQuotes()
adjustCase	Adjust the case of the email address. Possible options are: NO_CHANGE, LOWERCASE, LOWERCASE_LOCAL_PART_ONLY, LOWERCASE_DOMAIN_ONLY, UPPERCASE, UPPERCASE_LOCAL_PART_ONLY, UPPERCASE_DOMAIN_ONLY	adjustCase(CaseOption)
removeDots	Remove all dots from the local-part of the address	removeDots()
removeSubAddress	Remove any sub-addressing (or tagged-addressing) from the local-part of the address. For example, [email protected] will become [email protected]	removeSubAddress() or removeSubAddress(String)
performUnicodeNormalization	Perform unicode normalization on the local-part of the email address	performUnicodeNormalization() or performUnicodeNormalization(Normalizer.Form)

Additional Address Formats

Version 2.0.0 introduces new additional email address formats that can be obtained from
the Email object (similar to the normalized() method).

• Email#reference() returns an MD5 hash of the normalized email address.

    "[email protected]" => "1aedb8d9dc4751e229a335e371db8058"
  

• Email#redacted() returns a version of the normalized email address where the local-part
  is replaced with the SHA-1 hash of the local-part.

    "[email protected]" => "{a94a8fe5ccb19ba61c4c0873d391e987982fbbd3}@gmail.com"
  

• Email#munged() returns a version of the normalized email address where the local-part
  and domain are obfuscated with five asterisk characters.

    "[email protected]" => "te*****@gm*****"
  

Support for Leading and Trailing Dots in the Local-Part

While technically disallowed under published RFCs, some email providers (ex: GMail)
consider email addresses that have local-parts that start with or end with a dot . character
as valid. For example, GMail considers [email protected] valid, even though it is not
actually valid according to RFC.

JMail now gives you the option to consider these addresses valid as well. You must use an
EmailValidator with the allowNonstandardDots rule added to it to allow these addresses to pass validation.

EmailValidator validator = JMail.strictValidator()
        .allowNonstandardDots();

validator.isValid("[email protected]"); // returns true