> 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:

``bash
$ 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.

$3

`ts
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('support@neverbounce.com', 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();
`

$3

`ts
import NeverBounce from 'neverbounce';

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

// Verify an email with Promise syntax
client.single.check('support@neverbounce.com', 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.

$3

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
`

$3

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

`bash


Build the project

npm run build

Run an example (after compilation)

node dist/examples/account-info.js
`

$3

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

`bash
npm run example examples/single-check.ts
``

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