mailcheck.js

The Javascript library and jQuery plugin that suggests a right domain when your users misspell it in an email address.

Built on the foundations of the original mailcheck/mailcheck. Thank you for the great work.

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]", "hotmail.com" will be suggested. Similarly, if only the second level domain is misspelled, it will be corrected independently of the top level domain.

Installation

npm install --save @opositatest/mailcheck

Usage

ESM (recommended)

import { Mailcheck } from '@opositatest/mailcheck';

// Compatible alternative:
// import Mailcheck from '@opositatest/mailcheck';

Mailcheck.run({
  email: yourTextInput.value,
  domains: ['gmail.com', 'aol.com'],           // optional
  secondLevelDomains: ['hotmail'],             // optional
  topLevelDomains: ['com', 'net', 'org'],      // optional
  suggested(suggestion) {
    // show suggestion to user
    // suggestion = { address: 'test', domain: 'gmail.com', full: '[email protected]' }
  },
  empty() {
    // clear any existing suggestion
  }
});

CommonJS

const Mailcheck = require('@opositatest/mailcheck');

Mailcheck.run({ /* same options */ });

Browser via <script> tag

Use dist/mailcheck.browser.min.js, which also auto-registers the jQuery plugin if window.jQuery is present:

<script src="mailcheck.browser.min.js"></script>
<script>
  Mailcheck.run({ email: '[email protected]', suggested(s) { console.log(s.full); } });
</script>

With jQuery

Load mailcheck.browser.min.js after jQuery and use $.fn.mailcheck:

<script src="jquery.min.js"></script>
<script src="mailcheck.browser.min.js"></script>
<script>
$('#email').on('blur', function() {
  $(this).mailcheck({
    suggested(element, suggestion) {
      // show suggestion
    },
    empty(element) {
      // clear suggestion
    }
  });
});
</script>

The suggested callback receives the jQuery element and the suggestion object. The empty callback receives the jQuery element.

Suggestion object

{
  address: 'test',         // part before the @ sign
  domain: 'gmail.com',     // suggested domain
  full: '[email protected]'   // full suggested email
}

Domains

Mailcheck has inbuilt defaults if domains, secondLevelDomains or topLevelDomains are not provided. We recommend supplying your own based on the distribution of your users.

Replace the defaults entirely:

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

Or extend the global defaults:

Mailcheck.defaultDomains.push('customdomain.com');
Mailcheck.defaultSecondLevelDomains.push('yetanotherdomain');
Mailcheck.defaultTopLevelDomains.push('com.au');

Customization

Mailcheck uses the sift4 string similarity algorithm. You can replace it with your own:

Mailcheck.run({
  email: '[email protected]',
  distanceFunction(s1, s2) {
    // return a distance score; lower = more similar
  }
});

TypeScript

Types are included:

import { Mailcheck, MailcheckOptions, MailcheckSuggestion } from '@opositatest/mailcheck';

const opts: MailcheckOptions = {
  email: '[email protected]',
  suggested(suggestion: MailcheckSuggestion) {
    console.log(suggestion.full);
  }
};

Mailcheck.run(opts);

Tests

Requires Node.js ≥ 22.

npm test

Contributing

Pull requests are welcome. To get them accepted, please:

• Add test cases to spec/mailcheckSpec.js for any new behaviour.
• Run npm run build before committing — it runs lint, tests, and regenerates dist/. The pre-commit hook does this automatically after npm install.

Bugs and feature requests are managed in Issues.

Releasing

Releases are published from GitHub Actions to both npm and GitHub Packages.

Publish an existing version

Use this flow when the version is already set in package.json and you want to publish that exact version for the first time:

1. Make sure main contains the version you want to publish.
2. Go to GitHub → Releases → Draft a new release.
3. Create a new tag such as v2.0.0 from main.
4. Publish the release.

Publishing the GitHub Release triggers .github/workflows/publish.yml for npm and .github/workflows/publish-github-packages.yml for GitHub Packages. Both install dependencies, run npm run build, and publish the package.

If you already have the right version committed on main and need to publish it manually from GitHub, you can also run the Publish to npm workflow from Actions.

If you need the same manual fallback for GitHub Packages, run Publish to GitHub Packages from Actions.

Create the next release

For subsequent releases, use the Create Release GitHub Actions workflow:

1. Go to GitHub → Actions → Create Release.
2. Click Run workflow on main.
3. Choose patch, minor, or major.
4. Run the workflow.

Do not create the next release tag manually in GitHub for this flow. The workflow runs release-it, updates the version, creates the tag, pushes it, publishes the GitHub Release, and then publishes the package to both npm and GitHub Packages.

This will:

1. Verify you are on main, the working tree is clean, and in sync with origin
2. Bump the version in all files and regenerate dist/
3. Commit, tag and push to origin/main
4. Create the GitHub Release automatically via API
5. Publish the new version to npm
6. Publish the new version to GitHub Packages

This workflow publishes directly to both registries because a GitHub Release created with GITHUB_TOKEN does not trigger the separate publish workflows.

Local fallback

If you need to run the same flow locally, these commands still work:

npm run release          # interactive — prompts for patch/minor/major
npm run release -- patch # 2.0.0 → 2.0.1  (bug fixes)
npm run release -- minor # 2.0.0 → 2.1.0  (new features)
npm run release -- major # 2.0.0 → 3.0.0  (breaking changes)

License

Released under the MIT License.