Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Gem Version Build Status


This is the official NeverBounce V4 CLI written in Ruby. See also:


In your Gemfile, add:

gem "neverbounce-cli"

For edge versions of both, fetch gems directly:

gem "neverbounce-api", git: ""
gem "neverbounce-cli", git: ""

Install bundle, generate binstubs:

$ bundle install
$ bundle binstub neverbounce-cli

$ ls bin
nb-account-info  nb-jobs-delete   nb-jobs-parse    nb-jobs-search   nb-jobs-status   nb-single-check
nb-jobs-create   nb-jobs-download nb-jobs-results  nb-jobs-start    nb-poe-confirm

Create ~/.neverbounce.yml, add your API key there:

api_key: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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.


Before we begin, here's just 2 things you need to know to become a happy NeverBounce CLI user:

  1. Script names consistently map to our REST API v4.
    For example, nb-single-check calls single/check, nb-jobs-create calls jobs/create and so on.
  2. Every script supports --help and tells everything about itself.

Let's see what nb-single-check has to offer:

$ bin/nb-single-check --help
nb-single-check - Check a single e-mail

USAGE: nb-single-check [options] [VAR1=value] [VAR2=value] ...

-h, --help                       Show help information

Environment variables:
* API_KEY      - API key ("2ed45186c72f9319dc64338cdf16ab76b44cf3d1")
* EMAIL        - E-mail to check ("", "")
- ADDRESS_INFO - Request additional address info ("y", "n")
- API_URL      - Custom API URL ("")
- CREDITS_INFO - Request additional credits info ("y", "n")
- CURL         - Print cURL request and exit ("y", ["N"])
- RAW          - Print raw response body ("y", ["N"])
- TIMEOUT      - Timeout in seconds to verify the address ("5")

Now, let's check an e-mail:

$ bin/nb-single-check

| Result |      Flags       | SuggCorr | ExecTime |
| valid  | has_dns          |          |      651 |
|        | has_dns_mx       |          |          |
|        | role_account     |          |          |
|        | smtp_connectable |          |          |

With a bit of tuning:

$ bin/nb-single-check CREDITS_INFO=y

< above...>

| FreeRmn | FreeUsed | PaidRmn | PaidUsed |
|     969 |        1 | 1000000 |        0 |

Advanced usage

Print cURL command with CURL=y

Each of our scripts can print command to make the request using native curl binary on your OS. For example:

$ bin/nb-single-check CURL=y
curl --request GET --url --header Content-Type:\ application/json
--data-binary \{\"email\":\"\",\"key\":\"key123abc\"\}

You can now pass this command around, use it in scripts etc.

Print raw response with RAW=y

Each of our scripts can print raw server response without decoding it. For example:

$ bin/nb-single-check RAW=y

Although primary users of this feature is us at NeverBounce, you can also find it helpful once you encounter a server glitch and want to send us a meaningful bug report.


Minimum Ruby version is 2.0.


NeverBounce CLI in Ruby is free and is licensed under the MIT License. Copyright © 2017 NeverBounce.

You can’t perform that action at this time.