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.}"
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: "[email protected]")
if resp.ok?
puts "Result: #{resp.result}"
puts "Flags: #{resp.flags.join(' ')}"
else
puts "Error: #{resp.status}: #{resp.}"
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
Check a single address
resp = client.single_check(email: "[email protected]")
resp = client.single_check(email: "[email protected]", address_info: true, credits_info: true, timeout: 3)
Confirm frontend (Javascript Widget) verification
resp = client.poe_confirm(email: "[email protected]", transaction_id: "NBTRNS-abcdefg123456", confirmation_token: "abcdefg123456", result: "valid")
Create a bulk job
resp = client.jobs_create(supplied_input: [["[email protected]", "Alice Roberts"], ["[email protected]", "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)
Get bulk job status
resp = client.jobs_status(job_id: 123)
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| ...
Download bulk job result as CSV
resp = client.jobs_download(job_id: 123)
# Parse:
emails = CSV.parse(resp.raw)
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)
Parse an existing bulk job
resp = client.jobs_parse(job_id: 123)
Delete a bulk job
resp = client.jobs_delete(job_id: 123)
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.