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

advanced-email-existence

v1.0.8

Published

A Node.js library to check the existence of an email address by verifying with the domain's mail exchange (MX) servers and using SMTP commands.

Downloads

20

Readme

Advanced Email Existence

Advanced Email Existence is a Node.js library that verifies whether an email address exists by querying the domain's mail exchange (MX) servers. It performs real-time verification by connecting to the SMTP server(s) of the email's domain and sending partial SMTP commands to validate the existence of the email address.

Features

  • Email Format Validation: Ensures the email is in a valid format (e.g., [email protected]).
  • MX Record Lookup: Resolves mail exchange (MX) records for the email domain.
  • SMTP Verification: Connects to the domain's mail server and uses SMTP commands (HELO, MAIL FROM, RCPT TO) to verify the email.
  • Multiple Email Support: Validate an array of emails in parallel.
  • Customizable Timeout: Allows setting a custom timeout for SMTP connections.
  • Optimized for Speed: Uses parallel MX resolution and optimized connection timeouts.

Installation

Install the library using npm or yarn:

npm install advanced-email-existence

or

yarn add advanced-email-existence

Usage

Here’s how you can use the checkEmailExistence function, supporting both ES Modules and CommonJS:

Single Email Validation

ES Module Example

import checkEmailExistence from 'advanced-email-existence';

(async () => {
    const result = await checkEmailExistence('[email protected]');
    console.log(result); // { valid: true/false, undetermined: true/false }
})();

CommonJS Example

const checkEmailExistence = require('advanced-email-existence');

(async () => {
    const result = await checkEmailExistence('[email protected]');
    console.log(result); // { valid: true/false, undetermined: true/false }
})();

Parameters

  • email (string, required): The email address to verify.
  • timeout (integer, optional): The maximum time (in milliseconds) to wait for a response from the mail server. Default is 5000 milliseconds (5 seconds).
  • fromEmail (string, optional): The email address to use for the MAIL FROM SMTP command. Defaults to the email being verified.

Example with Custom Parameters

const result = await checkEmailExistence('[email protected]', 10000, '[email protected]');
console.log(result); // { valid: true, undetermined: false }

Response

The checkEmailExistence function returns a Promise that resolves to an object containing the following properties:

  • valid (boolean): Indicates whether the email address is valid (i.e., the mail server accepted it).
  • undetermined (boolean): Indicates whether the result is undetermined (i.e., the server did not respond conclusively).

Example Response

{
  "valid": true,
  "undetermined": false
}

Multi-Email Validation

To verify multiple email addresses simultaneously, use the checkEmailsExistence function. This function takes an array of emails and checks each email in parallel, returning the result for each.

ES Module Example (for multiple emails)

import { checkEmailsExistence } from 'advanced-email-existence';

(async () => {
    const emails = ['[email protected]', '[email protected]'];
    const results = await checkEmailsExistence(emails);
    console.log(results);
    // [
    //   { email: '[email protected]', valid: true, undetermined: false },
    //   { email: '[email protected]', valid: false, undetermined: true }
    // ]
})();

CommonJS Example (for multiple emails)

const { checkEmailsExistence } = require('advanced-email-existence');

(async () => {
    const emails = ['[email protected]', '[email protected]'];
    const results = await checkEmailsExistence(emails);
    console.log(results);
    // [
    //   { email: '[email protected]', valid: true, undetermined: false },
    //   { email: '[email protected]', valid: false, undetermined: true }
    // ]
})();

Parameters for Multi-Email Validation

  • emails (array, required): An array of email addresses to verify.
  • timeout (integer, optional): The maximum time (in milliseconds) to wait for a response from the mail server. Default is 5000 milliseconds (5 seconds).
  • fromEmail (string, optional): The email address to use for the MAIL FROM SMTP command. Defaults to the email being verified.

Example with Custom Parameters for Multi-Email Validation

const emails = ['[email protected]', '[email protected]'];
const results = await checkEmailsExistence(emails, 10000, '[email protected]');
console.log(results);
// Output: [
//   { email: '[email protected]', valid: true, undetermined: false },
//   { email: '[email protected]', valid: false, undetermined: true }
// ]

Response for Multiple Emails

The checkEmailsExistence function will return an array of results. Each result contains the following properties:

  • email (string): The email address being checked.
  • valid (boolean): Indicates whether the email address is valid (i.e., the mail server accepted it).
  • undetermined (boolean): Indicates whether the result is undetermined (i.e., the server did not respond conclusively).
  • error (string, optional): If an error occurs during validation, the error message is included.

Example Response for Multi-Email Check

[
  {
    "email": "[email protected]",
    "valid": true,
    "undetermined": false
  },
  {
    "email": "[email protected]",
    "valid": false,
    "undetermined": true,
    "error": "Connection timeout"
  }
]

Optimizations

  • Parallel MX Resolution: MX records are resolved in parallel for faster results.
  • Connection Timeout: The default timeout is 5000ms (5 seconds), configurable for faster or more lenient timeouts.
  • Port 25: SMTP connections are made over port 25 to maintain compatibility with most mail servers.
  • Error Handling: Undetermined results are returned if mail servers do not respond conclusively, ensuring robust handling of possible issues.

Common Use Cases

  1. Email Signup Validation: Ensure users provide valid email addresses during signup or registration.
  2. Bulk Email List Validation: Validate large lists of emails before sending out marketing campaigns.
  3. Database Cleansing: Remove invalid emails from your user database to improve the quality of your email list.

Limitations

  • SMTP Server Rate Limits: Some email servers apply rate-limiting to SMTP commands, potentially causing undetermined results.
  • Privacy Settings: Certain servers hide the existence of email addresses due to privacy or security policies.
  • False Positives: Catch-all domains may accept all email addresses, resulting in possible false positives.

License

This project is licensed under the MIT License.

Contributing

We welcome contributions! Feel free to open issues, submit pull requests, or suggest new features.

Contact

For issues, questions, or feature requests, please raise an issue on GitHub.


Dependencies

  • dns/promises: For resolving MX records of the email domain.
  • net: For establishing a TCP connection to the mail server and sending SMTP commands.

Future Enhancements

  • Add support for throttling requests to avoid rate-limiting issues.
  • Improve handling for catch-all domains to reduce false positives.