Looking for the V4 API wrapper with JavaScript? Check out version 4.x.x.

This is the official NeverBounce API NodeJS wrapper. It provides helpful methods to quickly implement our API in your NodeJS applications. Version 5.0.0 has been completely rewritten in TypeScript and requires Node.js 18 or higher

This package is not suitable for use in the browser! Only use it in server side applications!

Breaking Changes in 5.0.0

• Requires Node.js 18 or higher
• Converted to TypeScript with full type definitions
• Uses ES Modules instead of CommonJS
• Uses modern fetch API instead of https module
• Improved error handling with proper TypeScript types

Installation

To install use the following command:

$ npm install neverbounce --save

Basic Usage

The API username and secret key used to authenticate V3 API requests will not work to authenticate V4 API requests. If you are attempting to authenticate your request with the 8 character username or 12-16 character secret key the request will return an auth_failure error. The API key used for the V4 API will look like the following: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. To create new V4 API credentials please go here.

Example with async/await

import NeverBounce from 'neverbounce';

// Initialize NeverBounce client
const client = new NeverBounce({apiKey: 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'});

// Verify an email with async/await
async function verifyEmail() {
  try {
    // You can request additional information like address_info and credits_info
    const result = await client.single.check('[email protected]', true, true);
    
    console.log('Result: ' + result.getResult()); // prints: "valid"
    console.log('Result (numeric): ' + result.getNumericResult());
    console.log('Is Valid? ' + result.is(NeverBounce.result.valid));
    
    // Access the response data with proper typing
    const response = result.getResponse();
    
    if (response.address_info) {
      console.log('Host: ' + response.address_info.host);
    }
    
    if (response.credits_info) {
      console.log('Free Credits Used: ' + response.credits_info.free_credits_used);
      console.log('Paid Credits Used: ' + response.credits_info.paid_credits_used);
    }
  } catch (err) {
    // Errors are thrown and can be caught to handle specific error types
    if (err instanceof Error) {
      switch(err.type) {
        case NeverBounce.errors.AuthError:
          // The API credentials used are bad, have you reset them recently?
          break;
        case NeverBounce.errors.BadReferrerError:
          // The script is being used from an unauthorized source, you may need to
          // adjust your app's settings to allow it to be used from here
          break;
        case NeverBounce.errors.ThrottleError:
          // Too many requests in a short amount of time, try again shortly or adjust
          // your rate limit settings for this application in the dashboard
          break;
        case NeverBounce.errors.GeneralError:
          // A non recoverable API error occurred check the message for details
          break;
        default:
          // Other non specific errors
          console.error('Error:', err.message);
          break;
      }
    } else {
      console.error('Unknown error:', err);
    }
  }
}

verifyEmail();

Example with Promises (then/catch)

import NeverBounce from 'neverbounce';

// Initialize NeverBounce client
const client = new NeverBounce({apiKey: 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'});

// Verify an email with Promise syntax
client.single.check('[email protected]', true, true)
  .then(result => {
    console.log('Result: ' + result.getResult()); // prints: "valid"
    console.log('Result (numeric): ' + result.getNumericResult());
    console.log('Is Valid? ' + result.is(NeverBounce.result.valid));
    
    // Access the response data with proper typing
    const response = result.getResponse();
    
    if (response.address_info) {
      console.log('Host: ' + response.address_info.host);
    }
  })
  .catch(err => {
    // Handle errors with type checking
    if (err instanceof Error) {
      switch(err.type) {
        case NeverBounce.errors.AuthError:
          console.error('Auth Error:', err.message);
          break;
        case NeverBounce.errors.BadReferrerError:
          console.error('Bad Referrer Error:', err.message);
          break;
        case NeverBounce.errors.ThrottleError:
          console.error('Throttle Error:', err.message);
          break;
        case NeverBounce.errors.GeneralError:
          console.error('General Error:', err.message);
          break;
        default:
          console.error('Error:', err.message);
          break;
      }
    } else {
      console.error('Unknown error:', err);
    }
  });

For more information you can check out the /examples directory contained within the repository or visit our official documentation here.

Constants

The library exposes several constants that make working with jobs, verification results and errors easier. They can be accessed from the root NeverBounce object via the result, job, and errors properties.

Running Examples

There are several examples contained within the /examples directory included in this repo. The examples are available in both JavaScript and TypeScript.

Setting Up Environment Variables

The examples use environment variables for configuration. Create a .env file in the project root with the following content (substituting in your own API key):

NEVERBOUNCE_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Building and Running as JavaScript

Since the library is written in TypeScript, you'll need to compile it first to run the examples as JavaScript:

# Build the project
npm run build

# Run an example (after compilation)
node dist/examples/account-info.js

Running TypeScript Examples

To run the TypeScript examples, use the example script with the path to the TypeScript example:

npm run example examples/single-check.ts

This will execute the TypeScript file directly using ts-node without requiring a separate compilation step.