Skip to content

CookieBOY/clearout-node

 
 

Repository files navigation

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.

About

Clearout REST API

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%