NeverBounceCli-Ruby

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

Our Ruby API gem: https://github.com/NeverBounce/NeverBounceApi-Ruby.
Our full RubyDoc documentation: http://rubydoc.info/github/NeverBounce/NeverBounceCli-Ruby.

Installation

In your Gemfile, add:

gem "neverbounce-cli"

For edge versions of both, fetch gems directly:

gem "neverbounce-api", git: "https://github.com/NeverBounce/NeverBounceApi-Ruby.git"
gem "neverbounce-cli", git: "https://github.com/NeverBounce/NeverBounceCli-Ruby.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: key123abc

Usage

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

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.
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 ("https://staging-api.isp.com/v5")
- 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]

Response:
+--------+------------------+----------+----------+
| 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

Response:
<...like above...>

CreditsInfo:
+---------+----------+---------+----------+
| 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 https://api.neverbounce.com/v4/single/check --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 decoding it. For example:

$ bin/nb-single-check [email protected] RAW=y
{"status":"success","result":"valid","flags":["smtp_connectable","has_dns","has_dns_mx","role_account"],
"suggested_correction":"","execution_time":787}

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.

Compatibility

Minimum Ruby version is 2.0.