NeverBounceApi-Ruby

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

• Our full RubyDoc documentation: http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby.
• Our full REST API documentation: https://developers.neverbounce.com/v4.0/.
• RubyGems CLI: https://github.com/NeverBounce/NeverBounceCli-Ruby.

Installation

In your Gemfile, add:

gem "neverbounce-api"

For edge version, fetch the gem directly:

gem "neverbounce-api", git: "https://github.com/NeverBounce/NeverBounceApi-Ruby.git"

Install bundle:

$ bundle install

In your Ruby code, do a:

require "neverbounce"

Usage

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

client = NeverBounce::API::Client.new(api_key: "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}"
else
  # This is a `Response::ErrorMessage`.
  puts "Error: #{resp.status}: #{resp.message}"
end

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: "support@neverbounce.com")
if resp.ok?
  puts "Result: #{resp.result}"
  puts "Flags: #{resp.flags.join(' ')}"
else
  puts "Error: #{resp.status}: #{resp.message}"
end

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:

begin
  client = NeverBounce::API::Client.new(...)
  resp = client.jobs_create(...)
  ...
rescue => e
  # Log the error with full backtrace.
end

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: "alice@isp.com")
resp = client.single_check(email: "alice@isp.com", address_info: true, credits_info: true, timeout: 3)

Confirm frontend (Javascript Widget) verification

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

See also: method, REST.

Create a bulk job

resp = client.jobs_create(supplied_input: [["alice@isp.com", "Alice Roberts"], ["bob.smith@gmail.com", "Bob Smith"]])
resp = client.jobs_create(remote_input: "http://isp.com/emails.csv")
resp = client.jobs_create(remote_input: "http://isp.com/emails.csv", filename: "emails.csv", run_sample: true)
resp = client.jobs_create(remote_input: "http://isp.com/emails.csv", 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,
@free_credits_remaining=973>,@job_counts=#<NeverBounce::API::Response::AccountInfo::JobCounts:0x0056245c430310
@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.

Compatibility

Minimum Ruby version is 2.0.

Copyright

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