MailConfirm

A Node Js API for three stage email validation including the following;

• email pattern validation,
• MX mail server existence,
• mailbox existence.

NOTE: True mailbox existence may only be performed, with certainty, by sending a verification email and having the user verify their email.

Install

# yarn
yarn add mail-confirm
# npm
npm i mail-confirm

Usage

Usage Notes

• Ensure you execute this in an environment where SMTP port 25 is accessible. Failing to do so will throw error Mailbox check failed.
• Internal instance methods are exposed as Static methods. If you wish to build your own email verification routine, or only require one of these staged methods, simply call MailConfirm.[methodName]. See API Documentation below.

import MailConfirm from 'mail-confirm'

// promises
const email = new MailConfirm({
    emailAddress: 'test@gmail.com',
    timeout: 2000,
    mailFrom: 'my@email.com',
    invalidMailboxKeywords: ['noreply', 'noemail']
})

email.check().then(console.log).catch(console.log)

// async/await
const check = async (emailAddress) => {
    try{
        const email = new MailConfirm({ emailAddress })
        const result = await email.check()
        return result
    }catch(err){
        throw new Error(err)
    }
}

check('test@gmail.com')
/*
output => 
    { emailAddress: 'test@gmail.com',
    timeout: 2000,
    invalidMailboxKeywords: [],
    mailFrom: 'my@email.com',
    mailbox: 'test',
    hostname: 'gmail.com',
    mxRecords:
    [ { exchange: 'gmail-smtp-in.l.google.com', priority: 5 },
        { exchange: 'alt1.gmail-smtp-in.l.google.com', priority: 10 },
        { exchange: 'alt2.gmail-smtp-in.l.google.com', priority: 20 },
        { exchange: 'alt3.gmail-smtp-in.l.google.com', priority: 30 },
        { exchange: 'alt4.gmail-smtp-in.l.google.com', priority: 40 } ],
    smtpMessages:
    [ { command: 'HELO gmail-smtp-in.l.google.com',
        message: '220 mx.google.com ESMTP n6si1346674qtk.310 - gsmtp\r\n',
        status: 220 },
        { command: 'MAIL FROM: <email@example.org>',
        message: '250 mx.google.com at your service\r\n',
        status: 250 },
        { command: 'RCPT TO: <test@gmail.com>',
        message: '250 2.1.0 OK n6si1346674qtk.310 - gsmtp\r\n',
        status: 250 } ],
    isValidPattern: true,
    isValidMx: true,
    isValidMailbox: true,
    result: 'Mailbox is valid.' }
  */

API Documentation

MailConfirm

Kind: global class

• MailConfirm
  • new MailConfirm(config)
  • instance
    • .check() ⇒ Object
  • static
    • .resolvePattern(emailAddress, [invalidMailboxKeywords]) ⇒ boolean
    • .resolveMx(hostname) ⇒ Array.<Object>
    • .resolveSmtpMailbox(config) ⇒ Array.<object>

new MailConfirm(config)

Email address validation and SMTP verification API.

Param	Type	Description
config	Object	The email address you want to validate.
config.emailAddress	string	The email address you want to validate.
[config.mailFrom]	string	The email address used for the mail from during SMTP mailbox validation.
[config.invalidMailboxKeywords]	Array.<string>	Keywords you want to void, i.e. noemail, noreply etc.
[config.timeout]	number	The timeout parameter for SMTP mailbox validation.

mailConfirm.check() ⇒ Object

Runs the email validation routine and supplies a final result.

Kind: instance method of MailConfirm Returns: Object - - The instance state object containing all of the isValid* boolean checks, MX Records, and SMTP Messages.

MailConfirm.resolvePattern(emailAddress, [invalidMailboxKeywords]) ⇒ boolean

Determines if the email address pattern is valid based on regex and invalid keyword check.

Kind: static method of MailConfirm

Param	Type	Default	Description
emailAddress	string		The full email address ypu want to check.
[invalidMailboxKeywords]	Array.<string>	[]	An array of keywords to invalidate your check, ie. noreply
, noemail, etc.

MailConfirm.resolveMx(hostname) ⇒ Array.<Object>

Wrap of dns.resolveMx native method.

Kind: static method of MailConfirm Returns: Array.<Object> - - Returns MX records array { priority, exchange }

Param	Type	Description
hostname	string	The hostname you want to resolve, i.e. gmail.com

MailConfirm.resolveSmtpMailbox(config) ⇒ Array.<object>

Runs the SMTP mailbox check. Commands for HELO/EHLO, MAIL FROM, RCPT TO.

Kind: static method of MailConfirm Returns: Array.<object> - - Object of SMTP responses [ {command, status, message} ]

Param	Type	Description
config	Object	Object of parameters for Smtp Mailbox resolution.
config.emailAddress	string	The email address you want to check.
config.mxRecords	Array.<object>	The MX Records array supplied from resolveMx.
config.timeout	number	Timeout parameter for the SMTP routine.
config.mailFrom	string	The email address supplied to the MAIL FROM SMTP command.

Title: MailConfirm
Author: Elias Hussary eliashussary@gmail.com
License: MIT
Copyright: (C) 2017 Elias Hussary