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:
ruby
gem "neverbounce-api"
For edge version, fetch the gem directly:
ruby gem "neverbounce-api", git: "https://github.com/NeverBounce/NeverBounceApi-Ruby.git"
Install bundle:
sh
$ bundle install
In your Ruby code, do a:
ruby
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:
```ruby client = NeverBounce::API::Client.new(api_key: “secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”) # Insert YOUR key here. resp = client.account_info
if resp.ok?
puts “Free credits used: #respresp.credits_inforesp.credits_info.free_credits_used”
puts “Free credits remaining: #respresp.credits_inforesp.credits_info.free_credits_remaining”
else
# This is a Response::ErrorMessage.
puts “Error: #respresp.status: #respresp.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_failureerror. 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:
ruby
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.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:
ruby
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
ruby
resp = client.account_info
Check a single address
ruby
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
ruby
resp = client.poe_confirm(email: "[email protected]", transaction_id: "NBTRNS-abcdefg123456", confirmation_token: "abcdefg123456", result: "valid")
Create a bulk job
ruby
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
ruby
resp = client.jobs_status(job_id: 123)
Get bulk job results
```ruby 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
```ruby resp = client.jobs_download(job_id: 123)
Parse:
emails = CSV.parse(resp.raw) ```
List/search bulk jobs
```ruby 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
ruby
resp = client.jobs_start(job_id: 123)
Parse an existing bulk job
ruby
resp = client.jobs_parse(job_id: 123)
Delete a bulk job
ruby
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.