{"id":13598,"library":"neverbounce","title":"NeverBounce Node.js API Wrapper","description":"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.","status":"active","version":"5.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/NeverBounce/NeverBounceApi-NodeJS","tags":["javascript","email","email verification","email validation","email cleaning","verification","validation","cleaning","typescript"],"install":[{"cmd":"npm install neverbounce","lang":"bash","label":"npm"},{"cmd":"yarn add neverbounce","lang":"bash","label":"yarn"},{"cmd":"pnpm add neverbounce","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v5.0.0, the library uses ES Modules exclusively. CommonJS `require` is not supported.","wrong":"const NeverBounce = require('neverbounce');","symbol":"NeverBounce","correct":"import NeverBounce from 'neverbounce';"},{"note":"Result constants like `valid`, `invalid`, etc., are nested properties of the default `NeverBounce` export, not named exports.","wrong":"import { result } from 'neverbounce';","symbol":"NeverBounce.result","correct":"import NeverBounce from 'neverbounce';\n// ... then access NeverBounce.result.valid"},{"note":"Specific error types like `AuthError` are available as properties on the `NeverBounce.errors` object, which is itself nested under the default export.","wrong":"import { AuthError } from 'neverbounce';","symbol":"NeverBounce.errors","correct":"import NeverBounce from 'neverbounce';\n// ... then catch errors and check `err.type === NeverBounce.errors.AuthError`"}],"quickstart":{"code":"import NeverBounce from 'neverbounce';\n\n// Initialize NeverBounce client with your API key\nconst client = new NeverBounce({ apiKey: process.env.NEVERBOUNCE_API_KEY ?? '' });\n\nasync function verifyEmail() {\n  try {\n    // Verify an email, requesting address_info and credits_info\n    const result = await client.single.check('support@neverbounce.com', true, true);\n    \n    console.log('Verification Result: ' + result.getResult());\n    console.log('Numeric Result: ' + result.getNumericResult());\n    console.log('Is Valid? ' + result.is(NeverBounce.result.valid));\n    \n    const response = result.getResponse();\n    \n    if (response.address_info) {\n      console.log('Email Host: ' + response.address_info.host);\n    }\n    \n    if (response.credits_info) {\n      console.log('Free Credits Used: ' + response.credits_info.free_credits_used);\n      console.log('Paid Credits Used: ' + response.credits_info.paid_credits_used);\n    }\n  } catch (err) {\n    if (err instanceof Error) {\n      switch(err.type) {\n        case NeverBounce.errors.AuthError:\n          console.error('Authentication Error: Invalid API credentials.');\n          break;\n        case NeverBounce.errors.ThrottleError:\n          console.warn('Throttle Error: Too many requests, retrying shortly.');\n          break;\n        case NeverBounce.errors.GeneralError:\n          console.error('General API Error: ' + err.message);\n          break;\n        default:\n          console.error('An unexpected error occurred: ' + err.message);\n      }\n    } else {\n      console.error('An unknown error occurred:', err);\n    }\n  }\n}\n\nverifyEmail();","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your project's `node` engine version is `18.0.0` or greater. Update your `package.json` and local Node.js environment.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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`.","message":"Version 5.0.0 was a complete rewrite to TypeScript and exclusively uses ES Modules (`import`/`export` syntax). CommonJS (`require`) is no longer supported.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"This package is specifically designed for server-side Node.js applications and is explicitly *not* suitable for use in browser environments.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'5.0.0':47 '5.0.5':22 'activ':98 'adher':121 'api':3,18,82 'appear':97 'applic':40 'back':115 'branch':109 'browser':142 'cadenc':96 'choic':130 'clean':157,160 'commonj':89 'complet':43 'comprehens':61 'contemporari':123 'current':19 'definit':63 'demonstr':103 'depart':86 'develop':54 'differenti':111 'email':16,33,135,151,152,154,156 'embrac':51 'emphas':144 'es':72 'exclus':70 'explicit':139 'fetch':81 'full':57 'https':91 'import/export':75 'includ':56,112 'integr':32 'interfac':30 'javascript':53,150 'key':110 'leverag':78 'librari':49 'mainten':105 'make':126 'modern':52 'modul':73,92 'nativ':80 'natur':149 'network':84 'neverbounc':1,6,15,117 'node.js':2,11,124 'offici':10,114 'older':88 'ongo':104 'packag':7 'patch':101 'practic':55 'provid':24 'recent':100 'releas':95,102 'reliabl':129 'request':66,85 'respons':68 'rewrit':44 'robust':26 'safe':29 'server':38,133,147 'server-on':146 'server-sid':37,132 'servic':35 'side':39,134 'sinc':41 'standard':125 'strong':118 'support':59 'syntax':76 'task':137 'type':28,62,119 'type-saf':27 'typescript':58,161 'usag':93,143 'use':71 'v5':108 'valid':34,136,155,159 'verif':17,153,158 'version':21,46 'warn':140 'wrapper':4,12","created_at":"2026-04-20T01:55:20.197810+00:00","updated_at":"2026-04-20T01:55:20.197810+00:00","problems":[{"fix":"Obtain a valid V4 API key from the NeverBounce dashboard and ensure it is correctly configured in your application.","cause":"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`).","error":"Authentication Error: The API credentials used are bad, have you reset them recently? (or similar message containing 'auth_failure')"},{"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`.","cause":"Attempting to use the CommonJS `require()` function to import the `neverbounce` package, which is an ES Module since version 5.0.0.","error":"ERR_REQUIRE_ESM: require() of ES Module .../neverbounce/index.js from ... not supported."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://neverbounce.com","github":"https://github.com/NeverBounce/NeverBounceApi-NodeJS","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/neverbounce","openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}