smtp-ping

smtp-ping

Verify an email address through SMTP Ping

"SMTP Ping" is an attempt to connect and exchange information with a mail exchanger server using the SMTP protocol in order to validate the existence of a email box address.

The smtp ping flow consists of a DNS record query(MX) to find the mail exchanger server followed by an attempt to "send"(the email is never sent) an email to a recipient. The process is interrupted at the moment that the server confirms the existence of the recipient.

Note that pinging an email address does not produce a reliable result. Many mail exchanger servers implement strict policies when exchanging information with unknown hosts, so false positive results are expected.

Installation

npm install --save smtp-ping

Usage

const { ping, SmtpPingStatus } = require('smtp-ping');

ping('[e-mail]')
  .then(result => console.log(result))
  .catch(error => console.error(error));

Overriding the default settings:

const { ping, SmtpPingStatus } = require('smtp-ping');

const config = { sender: '[e-mail]', port: 26, timeout: 5000 };
ping('[e-mail]', config)
  .then(result => console.log(result))
  .catch(error => console.error(error));

The code above will produce the following result:

{
  complete:       boolean,
  status:         string,
  sender:         string,
  recipient:      string,
  fqdn:           string,
  host:           string,
  port:           number,
  timeout:        number,
  error:          <Error Object> | undefined,
  commandHistory: [
    { 
      command: string, 
      response: string, 
      code: number
    }
  ]
}

Attribute	Value	Default	Description
complete	true or false	None	Indicates if the ping is complete
status	'OK', 'INVALID' or 'UNKNOWN'	None	Email box address status
sender	'any@email'	Randomly Generated	Email address of the sender
recipient	'any@email'	None	Email address of the recipient
fqdn	'domain.com'	None	Domain of the recipient's email
host	'domain.com'	None	Mail exchanger server host
port	25	25	Mail exchanger server port
timeout	3000	3000	Socket idle timeout in milliseconds
error	Error object	None	Error object containing the details of the exception
commandHistory	[{command, response, code}]	None	Array of objects containing the SMTP commands and responses

The complete attribute will only be true in two scenarios:

1. Mail exchanger host not found(no MX record found) or client not able to connect to mail exchanger server.

2. SMTP ping flow is complete(sending and receiving SMTP commands).

The status attribute will be:

OK - Only if the smtp server explicitly confirms the availability of the mailbox address;

INVALID - If the smtp server explicitly confirms the mailbox is unavailable or if the client is unable to connect to the mail exchanger server;

UNKNOWN - For every other scenario(Idle Timeout, Transmission error, Connection closed before completing the smtp pipeline, etc).

License

This code is licensed under the MIT License.

All files located in the node_modules and external directories are externally maintained libraries used by this software which have their own licenses; we recommend you read them, as their terms may differ from the terms in the MIT License.