mailcheck.js

A jQuery plugin that suggests a right domain when your users misspell it in an email address.

What does it do?

When your user types in "user@hotnail.con", Mailcheck will suggest "user@hotmail.com".

At Kicksend, we use Mailcheck to help reduce typos in email addresses during sign ups.

See it live in action here.

Installation

For instant use, download src/jquery.mailcheck.min.js into javascripts directory. Use src/jquery.mailcheck.js if you want to hack on it, or have your own minimizer.
For hacking, fork the repo or git clone it.

Usage

First, include jQuery and Mailcheck into the page.

<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="jquery.mailcheck.min.js"></script>

Have a text field.

<form id="form">
  <input id="email" name="email" type="text" />
</form>

Now, attach Mailcheck to the text field. Remember to declare an array of domains you want to check against.

<script type="text/javascript">
  var domains = ['hotmail.com', 'gmail.com', 'aol.com'];
  $('form').on('blur', 'input#email', function() {
    $(this).mailcheck({
      domains: domains,   // optional
      suggested: function(element, suggestion) {
        // callback code
      },
      empty: function(element) {
        // callback code
      }
    });
  });
</script>

Mailcheck takes in two callbacks, suggested and empty. We recommend you supply both.

suggested is called when there's a suggestion. Mailcheck passes in the target element and the suggestion. The suggestion is an object with the following members:

{
  address: 'test',          // the address; part before the @ sign
  domain: 'hotmail.com',    // the suggested domain
  full: 'test@hotmail.com'  // the full suggested email
}

empty is called when there's no suggestion. Mailcheck just passes in the target element.

You can use the callbacks to display the appropriate visual feedback to the user.

Domains

The Mailcheck jQuery plugin defaults to a list of top email domains if the domain option isn't provided. We still recommend supplying your own domains based on the distribution of your users.

The included default domains are: yahoo.com, google.com, hotmail.com, gmail.com, me.com, aol.com, mac.com, live.com, comcast.net, googlemail.com, msn.com, hotmail.co.uk, yahoo.co.uk.

Customization

The Mailcheck jQuery plugin wraps Kicksend.mailcheck. The prime candidates for customization are the methods Kicksend.mailcheck.findClosestDomain and Kicksend.mailcheck.stringDistance.

Mailcheck currently uses the sift3 string similarity algorithm by Siderite.

Since Mailcheck runs client side, keep in mind file size, memory usage, and performance.

Tests

Mailcheck is tested with Jasmine. Load spec/spec_runner.html in your browser to run the tests.

Contributing

Let's make Mailcheck awesome. We're on the lookout for contributors.

And do send in those pull requests! To get them accepted, please:

Test your code. Add test cases to spec/mailcheckSpec.js.
Minify the plugin. Google's Closure Compiler is a good one.

Upcoming features, bugs and feature requests are managed in Issues.

Who's using Mailcheck?

Do you use Mailcheck? Tweet me your link.

Author

Derrick Ko (@derrickko)

License

Licensed under the MIT License.

peterdm / mailcheck