Step by Step Guide to Building a NeverBounce API Integration in Ruby

Aug 18, 2024 • 5 minute read

Introduction

Hey there, fellow Ruby enthusiast! Ready to supercharge your email validation game? Let's dive into integrating NeverBounce's powerful API into your Ruby project. We'll be using the neverbounce-api gem, which makes our lives a whole lot easier. Buckle up!

Prerequisites

Before we jump in, make sure you've got:

A Ruby environment set up (I know you've got this!)
A NeverBounce API key (grab one from their website if you haven't already)

Installation

First things first, let's get that gem installed:

gem install neverbounce-api

Easy peasy, right?

Configuration

Now, let's get our NeverBounce client up and running:

require 'neverbounce'

client = NeverBounce::API::Client.new(api_key: 'your_api_key_here')

Pro tip: Keep that API key safe! Consider using environment variables to store it.

Basic Usage

Single Email Verification

Let's start with verifying a single email:

result = client.single_check(email: '[email protected]')
puts result.status

Bulk Email Verification

Got a bunch of emails? No sweat:

job = client.jobs_create(input: ['[email protected]', '[email protected]'])
puts job.id

Advanced Features

Job Status Checking

Keep tabs on your bulk job:

status = client.jobs_status(job_id: job.id)
puts status.job_status

Fetching Results

Once the job's done, grab those results:

results = client.jobs_results(job_id: job.id)
results.results.each do |result|
  puts "#{result.email}: #{result.verification.result}"
end

Handling Rate Limits

NeverBounce has your back with built-in rate limiting. The gem will automatically retry if you hit the limit. Cool, huh?

Error Handling

Nobody's perfect, so let's catch those errors:

begin
  result = client.single_check(email: '[email protected]')
rescue NeverBounce::API::AuthError => e
  puts "Oops! Check your API key: #{e.message}"
rescue NeverBounce::API::GeneralError => e
  puts "Something went wrong: #{e.message}"
end

Best Practices

Use bulk verification for large lists - it's faster and more cost-effective.
Store verification results to avoid unnecessary re-checks.
Keep your API key secret. Seriously, don't commit it to your repo!

Example Use Cases

Integrating with a User Registration Form

post '/register' do
  email = params[:email]
  result = client.single_check(email: email)
  
  if result.status == 'valid'
    # Proceed with registration
  else
    # Show error message
  end
end

Cleaning an Existing Email List

emails = ['[email protected]', '[email protected]', '[email protected]']
job = client.jobs_create(input: emails)

# Wait for job to complete (you might want to use a background job for this)
loop do
  status = client.jobs_status(job_id: job.id)
  break if status.job_status == 'complete'
  sleep 5
end

results = client.jobs_results(job_id: job.id)
valid_emails = results.results.select { |r| r.verification.result == 'valid' }.map(&:email)

Conclusion

And there you have it! You're now equipped to integrate NeverBounce into your Ruby projects like a pro. Remember, clean email lists lead to better deliverability and happier users. Now go forth and validate those emails!

Need more info? Check out the NeverBounce API docs and the neverbounce-api gem documentation. Happy coding!