iDoRecall / email-normalize

Normalize email addresses to their canonical form: [e-mail] -> [e-mail]. Works for Google, Microsoft, FastMail, Yahoo!

iDoRecall:email-normalize

Client/server Meteor package to normalize email addresses to their canonical form:

• remove dots in GMail or email addresses hosted by similar services (Google Apps for Work, FastMail)
• remove address tags starting with '+', or '-' for Yahoo!, or '=' as well if desired
• converts alias domains to the canonical one, e.g. googlemail.com to gmail

This is useful for a variety of reasons:

• Get the real Gravatar of a user who registers for your service with [e-mail]. We use this at iDoRecall.
• Detect duplicate emails for fraud prevention.

Works for

• gmail.com, googlemail.com and google.com - the only domains Google is known to use for incoming email
• Any domain hosted with Google Apps for Work
• FastMail and domains hosted with FastMail
• Microsoft's outlook.com, hotmail.com, live.com
• Yahoo! domains

Pull requests to factor out the Meteor-independent code to use as a Node package are welcome.

Usage

The most common and general invocation is asynchronous:

let normalizedEmail = Email.normalize('[e-mail]', {detectProvider: true}, function callback(error, result) {
  // result will be [e-mail] if they use Google Apps, or unchanged otherwise
});

The general syntax is:

var normalizedEmail = Email.normalize(emailAddress, options, [callback]);  // [e-mail]

options is an object with the following keys, all optional:

• forceRemovePeriods - default false
• forceRemoveTags - default false; if true, will remove anything between the first '+', '-' or '=' and the '@' sign
• detectProvider - default false because it makes a DNS lookup request for the MX record of the domain to see if it might be a Google Apps for Business or a Fastmail domain, in which case appropriate rules will apply. If detectProvider is true, a callback is required on the client and optional on the server.
• callback - only required if detectProvider is true, and the code runs on the client

The email provider detection is done on the client by using the Enclout DNS API. If you run into any rate limits, please file an issue to add support for authentication.

Notes

If you're using this package to canonicalize email addresses for Gravatar, make sure to search (i.e. compute the hash for) the original email address first, since the user might legitimately always use something like [e-mail]. Also, the original email address should always have priority (consider a user who has Gravatars for both [e-mail] and [e-mail]).

When sending email use the original as well - it's respectful to your users to email them at the address they have supplied, since custom filter rules might depend on it.

Prior art

• normalize-email npm package - doesn't support Yahoo! or FastMail. We started contributing by fixing the naive removal of dots from Microsoft accounts (which was an error), but it quickly became apparent that a more comprehensive approach was needed.
• djanho-canonical-email - written in Python, doesn't support anything but Gmail
• soundcloud/normailize - Ruby, not maintained since March 2013

License and copyright

Maintainer: Dan Dascalescu (@dandv)

Copyright (C) 2015 iDoRecall, Inc.

The MIT License (MIT)