Clearout Node.js Library

The clearout node library provide convenient access to the Clearout REST API from applications written in server-side JavaScript to perform real-time, bulk email validation, email discovery. This programmatic interface will allow you to easily integrate into your use cases. Clearout infrastructure has been configured to retain high throughput, security and high precision accuracy. As long as credits are available in the account, you can perform clearout bulk verification or find support for any size list.

Documentation

See the Clearout API docs to know RESTFul endpoints

Requirements

Node >= 10 or higher.

Installation

Install the package with:

npm install @clearoutio/clearout --save

Usage

The package needs to be initialized with your Clearout's server app API token, which is available in the Clearout Apps Dashboard. If you dont find server app, please create one and copy the API token

Using as commonJS module with Promise:

const clearout = require('@clearoutio/clearout')('replace-with-your-api-token', { timeout: 5000 })

try {
  clearout.emailVerifier.verify({ email: '[email protected]' })
    .then(result => console.log(`Email ${result.email_address} status is ${result.status}, Is it safe to send? ${result.safe_to_send}`))
    .catch(error => console.error(error));
}
catch (error) {
  console.error(error)
}

Or using as ES modules with async/await:

import Clearout from '@clearoutio/clearout';

(async () => {
  try {
    const clearout = new Clearout('replace-with-your-api-token', { timeout: 5000 });
    const result = await clearout.emailVerifier.verify({ email: '[email protected]' });
    console.log(`Email ${result.email_address} status is ${result.status}, Is it safe to send? ${result.safe_to_send}`);
  } catch (error) {
    console.error(error)
  }
})();

Configuration

Initialize with config object

All service level settings for the Clearout package can be initialized, but they can be overridden when invoking the specific service methods.

import Clearout from '@clearoutio/clearout';
const clearout = new Clearout("replace-with-your-api-token", {timeout: 5000, ignore_result: true, ignore_duplicate_file: 'true'});

Option	Default	Description
token	null	Clearout server app API token
timeout	130,000 ms (Email Verifier) 30,000 ms (Email Finder)	Maximum time each request can take in milliseconds
ignore_result	false	Ignore result file even if its not downladed. Used when invoking list removal
ignore_duplicate_file	'false'	Whether to allow duplicate file upload based on file name and size.

Error Handling

All service methods return promise and throw an exception in case if the response status is failed, So the recommend approach would be to call service method in try...catch block

const clearout = require('@clearoutio/clearout')('replace-with-your-api-token', {timeout: 30000})

async function findEmail(name, domain) {
  try {
    console.log('Finding email, please wait...')
    const result = await clearout.emailFinder.find({ name, domain});
    console.log(`Email found ${result.emails[0].email_address} with confidence score ${result.confidence_score}`);
  } catch (error) {
    console.error('Errored:', error.message)
  }
}

findEmail('elon musk', 'tesla.com')

Email Verification Service

clearout.emailVerifier is ready to use object to host following methods that can be used to verify email address in real-time or to verify millions of email addresses from bulk file

Method	Parameters	Return	Description
verify({email[, timeout]})	email:String - Email address to verify timeout:Number - Overriable optional param with default value 130000 ms	Object with verified result	Instant email verification method to return the current status of email address
bulkVerify({file[, optimize, ignore_duplicate_file]})	file:String - Absolute filepath that contain email addresses to be upload optimize:String - Can either be 'highest_accuracy' or 'fastest_turnaround'. If not specified default would be 'highest_accuracy' ignore_duplicate_file:String - Whether to allow file with the same name and size that match with your recent upload. If not specified by default 'false'	Object with list_id	Verify bulk email addresses through file upload
getBulkVerifyProgressStatus({list_id})	list_id:String - List id to know the current progress status	Object with list progress status	To know the current progress status of bulk verify request
downloadBulkVerifyResult({list_id})	list_id:String - List id to download the result	Object with downloaded URL of verified result	Download verified result of the list
removeBulkVerifyList({list_id[, ignore_result]})	list_id:String - List id to remove ignore_result:Boolean - Overridable optional param with default true	Object with removed list details	Remove bulk verified list
isCatchAllEmail({email[,timeout]})	email:String - Email address to verify timeout:Number - Overridable optional param with default 90,000 ms	Object with email address catch all status	To know email address is accept all email type of not
isDisposableEmail({email[, timeout]})	email:String - Email address to verify, timeout:Number - Overridable optional param with default 90,000 ms	Object with email address disposable status	To know email address is diposable or temporary
isBusinessEmail({email[, timeout]})	email:String - Email address to verify timeout:Number - Overridable optional param with default 90,000 ms	Object with email address business status	To know email address belong to work or business
isFreeEmail({email[, timeout]})	email:String - Email address to verify, timeout:Number - Overridable optional param with default 90,000 ms	Object with email address free account status	To know email address belong to free email service providers
isRoleEmail({email[, timeout]})	email:String - Email address to verify, timeout:Number - Overridable optional param with default 90,000 ms	Object with email address role account status	To know email address belong to group or role based account
isGibberishEmail({email[, timeout]})	email:String - Email address to verify, timeout:Number - Overridable optional param with default 90,000 ms	Object with email address to indicate gibberish account	To know email address belong to gibberish account

Email Finder Service

clearout.emailFinder is ready to use object to host following methods that can be used to find an email address in real-time or to find email addresses of prospects from bulk file

Method	Parameters	Return	Description
find({name,domain[, timeout,queue]})	name:String - Person name domain:String - Person company name / domain timeout:Number - Overridable optional param with default 30,000 ms queue:Boolean - Flag to indicate whether email discovery can be performed in background even after the request timed out	Object with found email address or request queue id if request not fullfilled with in timeout	Instantly discover email address of any person giving their name and domain or company name
getStatus({qid})	qid:String - Queue ID received as part of the instant email finder response object	Object with found email address or progress status	To know the email finder request status in queue
bulkFind({file,[, ignore_duplicate_file]})	file:FileObject - Absolute filepath that contain person name and company name / domain to be upload ignore_duplicate_file:String - Whether to allow file with the same name and size that match with your recent upload. If not specified by default 'false'	Object with file list id	File bulk email addresses through file upload
getBulkFindProgressStatus({list_id})	list_id:String - List id for which to know the current progress status	Object with bulk find email status	To know the current progress status of bulk email find request
downloadBulkFindResult({list_id})	list_id:String - List id for result download	Object with downloaded URL of email finder result	Download email finder result of the list
removeBulkFindList({list_id[, ignore_result]})	list_id:String - List id to remove ignore_result:Boolean - Overridable optional param with default true	Object with removed list details	Remove bulk email finder list

Testing

To confirm that your integration works as intended without incurring credits, use the test email addresses listed below for all possible email verification results.

Test Email Address	Description
[email protected]	An invalid email address
[email protected]	An valid email address
[email protected]	Accept-all or Catch-all email address
[email protected]	An unknown email address
[email protected]	Safe to send email address
[email protected]	Not a safe to send email address
[email protected]	Risky email address
[email protected]	Disposable email address
[email protected]	Role or group based email address
[email protected]	Free mail server provider email address
[email protected]	Gibberish email address
[email protected]	Hard bounce email address
[email protected]	Soft bounce email address
[email protected]	An auto-suggested email address
[email protected]	Syntax error email address
[email protected]	Greylisted email address
[email protected]	Spamtrap email address
[email protected]	Found part of blacklisted email address
[email protected]	Found part of whitelisted email address
[email protected]	Found part of blacklisted domain
[email protected]	Found part of whitelisted domain
[email protected]	Domain does not exist email address
[email protected]	Not a mail server email address
[email protected]	Mailbox not found email address
[email protected]	Mail quota exceeded email address
[email protected]	DNS query timeout email address
[email protected]	Unroutable mail exchange server email address
[email protected]	Dormant email address
[email protected]	Receiving limit execeed email address

Versioning

This library follows Semantic Versioning.

This library is considered to be stable. Issues and requests against stable libraries are addressed with the highest priority.

More Information:
Clearout API Docs
Help

Contributing

Contributions welcome! Please reach out to [email protected]

MIT License

Copyright (c) 2022 - https://clearout.io

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.