@clearoutio/clearout

v1.1.8

Published

5 months ago

Clearout NodeJS module for Clearout REST API

Downloads

134

Clearout - An Official Email Verification and Email Finding Node.js Library

The Clearout node library is a wrapper of the Clearout REST API and allows developers to write applications in server-side JavaScript to perform real-time, bulk email verification and discovery. This programmatic interface will allow you to easily integrate into your use cases such as

Avoid capturing bad email addresses in your forms, chats, or anywhere else where email is accepted.
Bulk email verification to remove invalid, dead and fake emails from your email lists
Email finder to build pre-verified & accurate B2B leads for cold outreach

Clearout infrastructure has been designed to retain high throughput, security and precision accuracy. Bulk email verification or email finder support lists of any size, as long as credits are available in account

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 don't 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 the result file, even if it's not downloaded. 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, hence the recommended approach would be to call service method within a 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 a ready-to-use object that contains the methods for verifying email addresses in real-time and verifying millions of email addresses from a file

| Method | Parameters | Return |Description | | ------- | --------- | ----------- | -- | | verify({email[, timeout]}) | email:String - Email address to verify timeout:Number - Overridable 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 file path containing email addresses to be uploaded optimize:String - Can either be 'highest_accuracy' or 'fastest_turnaround'. If not specified, the default would be 'highest_accuracy' ignore_duplicate_file:String - Whether to allow files 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 |
| cancelBulkVerifyList({list_id}) | list_id:String - List id to cancel | Object with cancel list details | Cancel running bulk verify contact list | | downloadBulkVerifyResult({list_id}) | list_id:String - List id to download the result | Object with downloaded URL of verified result | Download verified result of the email 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 email 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 disposable 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 that has the following methods for finding 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 fulfilled 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 file path that contains person name and company name / domain to be uploaded ignore_duplicate_file:String - Whether to allow files 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 | | cancelBulkFinderList({list_id}) | list_id:String - List id to cancel | Object with cancel list details | Cancel running bulk email finding list | | 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 are welcome! Please reach out to [email protected]

MIT License

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.