Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
August 5, 2020 09:41
August 5, 2020 09:41
September 17, 2017 03:17
September 16, 2017 18:55
September 17, 2017 01:07
September 16, 2017 18:55
September 17, 2017 03:33
September 16, 2017 18:55
January 16, 2018 15:56

Gem Version Build Status


This is the official NeverBounce V4 API for Ruby. See also:


In your Gemfile, add:

gem "neverbounce-api"

For edge version, fetch the gem directly:

gem "neverbounce-api", git: ""

Install bundle:

$ bundle install

In your Ruby code, do a:

require "neverbounce"


To talk to the API, create a Client object and call one of its request methods. For example, let's get account info:

client = "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")   # Insert YOUR key here.
resp = client.account_info

if resp.ok?
  puts "Free credits used: #{resp.credits_info.free_credits_used}"
  puts "Free credits remaining: #{resp.credits_info.free_credits_remaining}"
  # This is a `Response::ErrorMessage`.
  puts "Error: #{resp.status}: #{resp.message}"

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.

Now, let's check a single e-mail:

resp = client.single_check(email: "")
if resp.ok?
  puts "Result: #{resp.result}"
  puts "Flags: #{resp.flags.join(' ')}"
  puts "Error: #{resp.status}: #{resp.message}"

Error handling

Our API library raises subclasses of API::Error for higher-level errors and subclasses of StandardError in all other cases. This wrapper guarantees that you catch all errors from the API library:

  client =
  resp = client.jobs_create(...)
rescue => e
  # Log the error with full backtrace.

If you're running a background job, it's generally better to log the full backtrace in case you encounter unexpected server behaviour or something like that.

Client requests

This a is complete list of requests supported by API::Client.

Get account information

resp = client.account_info

See also: method, REST.

Check a single address

resp = client.single_check(email: "")
resp = client.single_check(email: "", address_info: true, credits_info: true, timeout: 3)

Confirm frontend (Javascript Widget) verification

resp = client.poe_confirm(email: "", transaction_id: "NBTRNS-abcdefg123456", confirmation_token: "abcdefg123456", result: "valid")

See also: method, REST.

Create a bulk job

resp = client.jobs_create(supplied_input: [["", "Alice Roberts"], ["", "Bob Smith"]])
resp = client.jobs_create(remote_input: "")
resp = client.jobs_create(remote_input: "", filename: "emails.csv", run_sample: true)
resp = client.jobs_create(remote_input: "", filename: "emails.csv", auto_start: true)

See also: method, REST.

Get bulk job status

resp = client.jobs_status(job_id: 123)

See also: method, REST.

Get bulk job results

resp = client.jobs_results(job_id: 123)
resp = client.jobs_results(job_id: 123, page: 1, per_page: 20)    # Grab the first 20.

# Process items:
resp.results.items.each do |item| ...

See also: method, Item, REST.

Download bulk job result as CSV

resp = client.jobs_download(job_id: 123)

# Parse:
emails = CSV.parse(resp.raw)

See also: method, REST.

List/search bulk jobs

resp = client.jobs_search
resp = client.jobs_search(page: 1, per_page: 20)    # Grab the first 20.

# Process items:
resp.results.each do |item|

See also: method, Result, REST.

Start an existing bulk job

resp = client.jobs_start(job_id: 123)

See also: method, REST.

Parse an existing bulk job

resp = client.jobs_parse(job_id: 123)

See also: method, REST.

Delete a bulk job

resp = client.jobs_delete(job_id: 123)

See also: method, REST.

Debugging in the console

When you make requests from the console, you'll notice that the responses don't show you any content, i.e. instance variables:

irb> resp = client.account_info
=> #<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8>
irb> resp.inspect
=> "#<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8>"

It happens because by design our response containers lazy-load their attributes upon first access. Let's request an attribute:

irb> resp.status
=> "success"
irb> resp
=> #<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8 @status="success">

In order to load all attributes use method .touch, like this:

irb> resp.touch
=> #<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8 @status="success",
@execution_time=98, @credits_info=#<NeverBounce::API::Response::CreditsInfo::Paid:0x0056245c430478
@paid_credits_used=0, @free_credits_used=0, @paid_credits_remaining=1000000,
@completed=10, @processing=0, @queued=0, @under_review=0>>

This is true for all API response containers and sub-containers. See #touch in the docs.

Advanced usage

For most regular tasks Client is powerful enough. However, if you need more control, you can use Request, Session and Response classes directly. Please refer to the online docs.

For example, our CLI gem uses them.

Command line interface

We've got a gem called neverbounce-cli which gives you a set of powerful CLI scripts to use our API.

We recommend to install the CLI to have these tools at hand.


Minimum Ruby version is 2.0.

NeverBounce API for Ruby is free and is licensed under the MIT License. Copyright © 2017 NeverBounce.


The official Ruby wrapper for the NeverBounce API







No packages published

Contributors 4