npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mailcheck

v1.1.1

Published

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

Downloads

430,250

Readme

mailcheck.js

TravisCI Build Status

The Javascript library and 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 "[email protected]", Mailcheck will suggest "[email protected]".

Mailcheck will offer up suggestions for second and top level domains too. For example when a user types in "[email protected]" then "hotmail.com" will be suggested. Similarly if only the second level domain is miss-spelled then it will be corrected independently of the top level domain allowing for fine resolution tweaking if desired.

At Kicksend, we use Mailcheck to help reduce typos in email addresses during sign ups. It has reduced our sign up confirmation email bounces by 50%.

diagram

See it live in action here.

Installation

For instant use, download the minified library mailcheck.min.js into your javascripts directory. mailcheck.js is also available unminimised if you want to hack on it, or have your own minimizer.

Bower

> bower install --save mailcheck

Node/Browserify

> npm install --save mailcheck

Usage with jQuery

First, include jQuery and Mailcheck into the page.

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

Have a text field.

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

Now, attach Mailcheck to the text field. You can declare an array of domains, second level domains and top level domains you want to check against.

<script>
var domains = ['gmail.com', 'aol.com'];
var secondLevelDomains = ['hotmail']
var topLevelDomains = ["com", "net", "org"];

var superStringDistance = function(string1, string2) {
  // a string distance algorithm of your choosing
}

$('#email').on('blur', function() {
  $(this).mailcheck({
    domains: domains,                       // optional
    secondLevelDomains: secondLevelDomains, // optional
    topLevelDomains: topLevelDomains,       // optional
    distanceFunction: superStringDistance,  // 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: 'gmail.com',    // the suggested domain
  full: '[email protected]'  // the full suggested email
}

Mailcheck does not want to get in the way of how you can show suggestions. Use the suggestion object to display suggestions in your preferred manner.

empty is called when there's no suggestion. Mailcheck just passes in the target element. It is a good idea to use this callback to clear an existing suggestion.

Usage without jQuery

Mailcheck is decoupled from jQuery, so its usage without jQuery is almost identical.

Using the example from above, you would call Mailcheck.run instead.

<script>
Mailcheck.run({
  email: yourTextInput.value,
  domains: domains,                       // optional
  topLevelDomains: topLevelDomains,       // optional
  secondLevelDomains: secondLevelDomains, // optional
  distanceFunction: superStringDistance,  // optional
  suggested: function(suggestion) {
    // callback code
  },
  empty: function() {
    // callback code
  }
});
</script>

The rest works similarly. In fact, the Mailcheck jQuery plugin just wraps Mailcheck.run.

Usage on Node.js

If you're running this on Node.js, you can just require('mailcheck') to get the mailcheck object, and call run on that:

var mailcheck = require('mailcheck');

mailcheck.run({
  // see 'usage without jQuery' above.
});

Domains

Mailcheck has inbuilt defaults if the domains, secondLevelDomains or topLevelDomains options aren't provided. We still recommend supplying your own domains based on the distribution of your users.

Adding your own Domains

You can replace Mailcheck's default domain/TLD suggestions by supplying replacements to mailcheck.run:

Mailcheck.run({
  domains: ['customdomain.com', 'anotherdomain.net'], // replaces existing domains
  secondLevelDomains: ['domain', 'yetanotherdomain'], // replaces existing SLDs
  topLevelDomains: ['com.au', 'ru'] // replaces existing TLDs
});

Alternatively, you can extend Mailcheck's global set of default domains & TLDs by adding items to Mailcheck.defaultDomains and Mailcheck.defaultTopLevelDomains:

Mailcheck.defaultDomains.push('customdomain.com', 'anotherdomain.net') // extend existing domains
Mailcheck.defaultSecondLevelDomains.push('domain', 'yetanotherdomain') // extend existing SLDs
Mailcheck.defaultTopLevelDomains.push('com.au', 'ru') // extend existing TLDs

Customization

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

Mailcheck currently uses the sift3 string similarity algorithm by Siderite. You can modify the inbuilt string distance function, or pass in your own when calling Mailcheck.

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 or run npm test from the command line to test in node.

Contributing

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

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

  • Test your code. Add test cases to spec/mailcheckSpec.js, and run it across browsers (yes, including IE).
  • Minify the plugin by running grunt in the Mailcheck directory.

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

Developing on Nitrous.IO

Start contributing to Mailcheck instantly on Nitrous.IO:

Hack mailcheck/mailcheck on Nitrous.IO

Who have used Mailcheck?

Do you use Mailcheck? Tweet me your link.

Related Links

Core Team

License

Released under the MIT License.