Email Verification API
Ruby & Rails Integration Guide 2026

require "net/http"
require "uri"
require "json"

API_KEY = ENV["BOUNCEZERO_API_KEY"]
BASE_URL = "https://api.bouncezero.io/api/v1"

def verify_email(email)
  uri  = URI("#{BASE_URL}/verify")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request["X-API-Key"]    = API_KEY
  request["Content-Type"]  = "application/json"
  request.body = { email: email }.to_json

  response = http.request(request)
  JSON.parse(response.body, symbolize_names: true)
end

result = verify_email("[email protected]")
puts result
# => {
#      email: "[email protected]",
#      score: 98,                    # 0-100
#      classification: "valid",      # "valid" | "invalid"
#      is_deliverable: true,
#      risk_level: "low",            # "low" | "medium" | "high"
#      checks: { syntax: true, domain_valid: true, not_disposable: true, ... },
#      metadata: { internal_classification: "verified", refunded: nil, ... }
#    }

require "faraday"
require "json"

API_KEY = ENV["BOUNCEZERO_API_KEY"]

def bouncezero_client
  Faraday.new("https://api.bouncezero.io") do |f|
    f.request  :json
    f.response :json, symbolize_names: true
    f.headers["X-API-Key"] = API_KEY
  end
end

def verify_email(email)
  response = bouncezero_client.post("/api/v1/verify", { email: email })
  response.body
end

result = verify_email("[email protected]")
puts result[:classification]                      # => "valid"
puts result[:score]                               # => 96
puts result.dig(:metadata, :internal_classification) # => "verified"

require "net/http"
require "json"

class BounceZeroEmailValidator < ActiveModel::EachValidator
  API_KEY  = ENV["BOUNCEZERO_API_KEY"]
  ENDPOINT = URI("https://api.bouncezero.io/api/v1/verify")

  def validate_each(record, attribute, value)
    return if value.blank?

    result = call_api(value)
    return unless result

    if result.dig(:metadata, :internal_classification) == "disposable"
      record.errors.add(attribute, :disposable, message: "Please use a work or personal email address")
    elsif result[:classification] == "invalid" && !result.dig(:metadata, :refunded)
      # refunded = could not be verified (credit returned), so do not block on it
      record.errors.add(attribute, :invalid, message: "doesn't appear to be a valid email address")
    end
  rescue StandardError
    # Fail open on API errors - do not block signup
  end

  private

  def call_api(email)
    http    = Net::HTTP.new(ENDPOINT.host, ENDPOINT.port)
    http.use_ssl = true
    req = Net::HTTP::Post.new(ENDPOINT)
    req["X-API-Key"]    = API_KEY
    req["Content-Type"]  = "application/json"
    req.body = { email: email }.to_json
    res = http.request(req)
    JSON.parse(res.body, symbolize_names: true)
  end
end

# In your User model:
# validates :email, presence: true, bouncezero_email: true

class EmailVerificationWorker
  include Sidekiq::Worker
  sidekiq_options retry: 2, queue: :verification

  def perform(user_id)
    user = User.find_by(id: user_id)
    return unless user

    result = BounceZeroService.verify(user.email)
    return unless result

    case result[:classification]
    when "invalid"
      user.update!(email_verified_at: nil, email_status: "invalid")
      # Optional: flag for manual review or send re-registration prompt
    when "valid"
      user.update!(email_verified_at: Time.current, email_status: "valid")
    end

    user.update!(
      email_disposable: result.dig(:metadata, :internal_classification) == "disposable",
      email_score: result[:score]
    )
  end
end

# Trigger from UsersController#create or Devise registrations_controller:
# EmailVerificationWorker.perform_async(@user.id)