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


In your Gemfile, add:

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-jobs-create   nb-jobs-download  nb-jobs-results  nb-jobs-start   nb-single-check

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

api_key: key123abc


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 check a single e-mail:

$ 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")

Let's do it:

$ bin/nb-single-check [email protected]

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

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

Print raw response with RAW=y

Each of our scripts can print raw server response without trying to decode it. For example:

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

Although primary users of this feature is us at NeverBounce, you can also benefit from it, e.g. if you encounter a server glitch and want to supply 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.