neverbounce

library0.2.0jsnpmunverified

The `neverbounce` package is the official Node.js wrapper for the NeverBounce email verification API, currently at version 5.0.5. It provides a robust, type-safe interface for integrating email validation services into server-side applications. Since its complete rewrite in version 5.0.0, the library has embraced modern JavaScript development practices, including full TypeScript support with comprehensive type definitions for both requests and responses. It exclusively uses ES Modules for import/export syntax and leverages the native `fetch` API for network requests, departing from older CommonJS and `https` module usage. The release cadence appears active, with recent patch releases demonstrating ongoing maintenance for the v5 branch. Key differentiators include its official backing by NeverBounce, strong typing, and adherence to contemporary Node.js standards, making it a reliable choice for server-side email validation tasks. It explicitly warns against browser usage, emphasizing its server-only nature.

communication http-networking serialization

npm install neverbounce

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEVERBOUNCE

neverbounce

communicationjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NeverBounce

✓ import NeverBounce from 'neverbounce';

✗ const NeverBounce = require('neverbounce');

Since v5.0.0, the library uses ES Modules exclusively. CommonJS `require` is not supported.

NeverBounce.result

✓ import NeverBounce from 'neverbounce'; // ... then access NeverBounce.result.valid

✗ import { result } from 'neverbounce';

Result constants like `valid`, `invalid`, etc., are nested properties of the default `NeverBounce` export, not named exports.

NeverBounce.errors

✓ import NeverBounce from 'neverbounce'; // ... then catch errors and check `err.type === NeverBounce.errors.AuthError`

✗ import { AuthError } from 'neverbounce';

Specific error types like `AuthError` are available as properties on the `NeverBounce.errors` object, which is itself nested under the default export.

This quickstart demonstrates how to initialize the NeverBounce client, perform an email verification, access detailed results and response data, and handle various API-specific errors using async/await.

import NeverBounce from 'neverbounce'; // Initialize NeverBounce client with your API key const client = new NeverBounce({ apiKey: process.env.NEVERBOUNCE_API_KEY ?? '' }); async function verifyEmail() { try { // Verify an email, requesting address_info and credits_info const result = await client.single.check('support@neverbounce.com', true, true); console.log('Verification Result: ' + result.getResult()); console.log('Numeric Result: ' + result.getNumericResult()); console.log('Is Valid? ' + result.is(NeverBounce.result.valid)); const response = result.getResponse(); if (response.address_info) { console.log('Email 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) { if (err instanceof Error) { switch(err.type) { case NeverBounce.errors.AuthError: console.error('Authentication Error: Invalid API credentials.'); break; case NeverBounce.errors.ThrottleError: console.warn('Throttle Error: Too many requests, retrying shortly.'); break; case NeverBounce.errors.GeneralError: console.error('General API Error: ' + err.message); break; default: console.error('An unexpected error occurred: ' + err.message); } } else { console.error('An unknown error occurred:', err); } } } verifyEmail();

Debug

Known issues

breakingVersion 5.0.0 and above require Node.js 18 or higher. Projects on older Node.js versions must upgrade or use a `4.x.x` version of the package.

fix

Ensure your project's `node` engine version is `18.0.0` or greater. Update your `package.json` and local Node.js environment.

affects: >=5.0.0

breakingVersion 5.0.0 was a complete rewrite to TypeScript and exclusively uses ES Modules (`import`/`export` syntax). CommonJS (`require`) is no longer supported.

fix

Migrate your application to use ES Module `import` syntax for all NeverBounce library imports. Update your `package.json` to include `"type": "module"` if necessary, or use a `.mjs` extension for files using `import`.

affects: >=5.0.0

breakingThe entire codebase was converted to TypeScript in v5.0.0, introducing full type definitions. This will affect JavaScript users who may see new tooling suggestions or TypeScript compilation errors if migrating an existing codebase without adapting to types.

fix

For JavaScript users, this is largely additive. For TypeScript users, ensure your code adheres to the new types; this may involve updating variable declarations or function signatures based on the new API response and request typings.

affects: >=5.0.0

gotchaThe API key format for NeverBounce V4 (used by this wrapper) is `secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. V3 API usernames (8 characters) and secret keys (12-16 characters) will result in an `auth_failure` error.

fix

Ensure you are using a V4 API key. Generate new V4 API credentials from your NeverBounce dashboard if you are still using V3 keys.

affects: >=4.0.0

gotchaThis package is specifically designed for server-side Node.js applications and is explicitly *not* suitable for use in browser environments.

fix

Only use this package in Node.js server-side code. For client-side email validation, consider alternative approaches or direct API calls that respect cross-origin policies.

affects: >=4.0.0

Errors

Common errors & fixes

Authentication Error: The API credentials used are bad, have you reset them recently? (or similar message containing 'auth_failure')

Using an incorrect API key format, such as an older V3 API username/secret key instead of a V4 API key (e.g., `secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).

fix

Obtain a valid V4 API key from the NeverBounce dashboard and ensure it is correctly configured in your application.

ERR_REQUIRE_ESM: require() of ES Module .../neverbounce/index.js from ... not supported.

Attempting to use the CommonJS `require()` function to import the `neverbounce` package, which is an ES Module since version 5.0.0.

fix

Migrate your import statements from `const NeverBounce = require('neverbounce');` to `import NeverBounce from 'neverbounce';`. If your project is CommonJS, consider adding `"type": "module"` to your `package.json` or switching the file extension to `.mjs`.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/NeverBounce/NeverBounceApi-NodeJS ↗

packagehttps://www.npmjs.com/package/neverbounce ↗

homepagehttps://neverbounce.com ↗