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 ("[email protected]", "[email protected]")
- 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 [email protected]

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

With a bit of tuning:

$ bin/nb-single-check [email protected] CREDITS_INFO=y

< above...>

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

Advanced usage

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

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

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

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

$ bin/nb-single-check [email protected] 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.