Email validation with more than 10K disposable/temporary email domains
npm install emailvalidEmail Validation is a library that validates email addresses and checks againts more than 10K domains used for disposable emails
If you want to block disposable email addresses at signup, or if you are a B2B company and want only professional email adresses, this is the solution for you :)
This library does multiple verifications:
- Email format validation
- Free email address (@gmail.com, @hotmail.com, @protonmail.com, ...)
- Disposable email address (@maildrop.cc, @fakemail.net, @trashmail.com, ...)
- Possible typos in popular email domains
Email Validation has 0 dependency, 100% coverage, and is fully configurable.
- Installation
- Usage
- Configuration
- Result
- Contributions
- License
Install using npm:
``bash`
npm install emailvalid
or Yarn yarn:
`bash`
yarn add emailvalid
Email Validation is initialized with a list of default domains
`javascript
const EmailValidation = require('emailvalid')
const ev = new EmailValidation()
// This email will be invalid because it is a free email
const result = ev.check('random@gmail.com')
console.log(${result.email} validity: ${result.valid})
// This email will be invalid because it is a disposable email
const result2 = ev.check('iamadisposableemail@yopmail.com')
console.log(${result2.email} validity: ${result2.valid})
// You can also check for possible typos
const result3 = ev.check('john@gmil.com')
if (result3.typo) console.log(Did you mean ${result3.typo}?)
`
The output will be an object with some information on the validity (see result section)
Email Validation can be configured with more advanced options as an object:
- whitelist _(Array)_ Add some email domains you want to whitelist (default is [])blacklist
- _(Array)_ Add some email domains you want to blacklist (default is [])allowFreemail
- _(Boolean)_ Allow free emails such as @gmail.com, ... (default is false)allowDisposable
- _(Boolean)_ Allow disposable emails such as @trashmail.com, ... (default is false)
You can for example choose to allow freemails, and add a domain baddomain.com in addition to the preconfigured list
#### Advanced configuration example
`javascript
const EmailValidation = require('emailvalid')
const ev = new EmailValidation({ allowFreemail: true, blacklist: ['baddomain.com'] })
// This one should have result.valid = true because we allowed free mails such as gmail.com
ev.check('random@gmail.com')
// But this one is blacklisted now
ev.check('paul@baddomain.com')
`
Or if you want to disallow all free mails, except gmail.com :
`javascript
const ev = new EmailValidation({ whitelist: ['gmail.com'] })
`
You can check some examples in example.js
#### Updating options on the fly
In case you need to update options after initialization, you can do it on the fly with different methods:
- whitelist _(Function)_ Add a new domain to the whitelistblacklist
- _(Function)_ Add a new domain to the blacklistsetOptions
- _(Function)_ Changes the options
`javascript
const EmailValidation = require('emailvalid')
const ev = new EmailValidation()
// This adds a new domain as invalid
ev.blacklist('baddomain.com')
// This marks a domain as valid
ev.whitelist('gooddomain.com')
// This changes options to allow freemails
ev.setOptions({ allowFreemail: true })
`
Email Validation will output an object with the following information:
- email _(String)_ Email in a standardized format (trimed and lowercased)domain
- _(String)_ Domain from the emailvalid
- _(Boolean)_ Is the email address valid?errors
- _(Array)_ List of errors if anytypo
- _(String)_ Is there any possible typo in the email?
Errors contains strings and can be one of :
- invalid Email is not present of format is invaliddisposable
- Email is disposable (and not whitelisted or allowed in parameters)freemail
- Email is a free mail (and not whitelisted or allowed in parameters)blacklisted
- Email is blacklisted in parameters
#### Example :
`javascript
const EmailValidation = require('emailvalid')
const ev = new EmailValidation()
const result = ev.check('RANDOM@gmail.com')
console.log(result)
// This will return :
// {
// email: 'random@gmail.com',
// domain: 'gmail.com'
// valid: false,
// errors: ['freemail'],
// typo: null
// {
`
If you need a simple way to add domains to the list, just run yarn add-domain [DOMAIN] [CATEGORY]
For example yarn add-domain freemail gmail.com`
Then feel free to create Pull Requests :)