No description, website, or topics provided.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
exe
lib
spec
.codeclimate.yml
.gitignore
.rspec
.rubocop.yml
.travis.yml
.yardopts
Gemfile
Gemfile.lock
LICENSE
README.md
neverbounce-cli.gemspec

README.md

Gem Version Build Status

NeverBounceCli-Ruby

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

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: 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.

Usage

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 ("alice@isp.com", "bob.smith+1@domain.com")
- 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=support@neverbounce.com

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=support@neverbounce.com 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=support@neverbounce.com CURL=y
curl --request GET --url https://api.neverbounce.com/v4/single/check --header Content-Type:\ application/json
--data-binary \{\"email\":\"support@neverbounce.com\",\"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=support@neverbounce.com 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.

Copyright

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