Email Verification in Ruby on Rails

# Gemfile — use net/http (built-in) or faraday
gem 'faraday'  # optional, but cleaner for API calls

mailbeam:
  key: mb_live_xxxxxxxxxxxxxxxxxxxx

# app/validators/mailbeam_validator.rb
require 'faraday'
require 'json'

class MailbeamValidator < ActiveModel::EachValidator
  MIN_SCORE = options[:min_score] || 60

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

    result = verify_email(value.downcase.strip)
    return if result.nil? # API error — fail open

    unless result['valid'] && result['score'].to_i >= MIN_SCORE
      reason = result['reason']
      message = case reason
                when 'disposable_domain' then 'must not be a temporary email address'
                when 'no_mx_records'     then 'domain cannot receive email'
                when 'smtp_rejected'     then 'does not appear to exist'
                else 'is not a valid email address'
                end
      record.errors.add(attribute, message)
    end
  end

  private

  def verify_email(email)
    conn = Faraday.new('https://api.mailbeam.dev') do |f|
      f.request :json
      f.response :json
      f.adapter Faraday.default_adapter
    end

    response = conn.post('/v1/verify', { email: email }) do |req|
      req.headers['Authorization'] = "Bearer #{Rails.application.credentials.mailbeam.key}"
      req.options.timeout = 5
    end

    response.body if response.success?
  rescue StandardError => e
    Rails.logger.error "[Mailbeam] verify failed: #{e.message}"
    nil # fail open
  end
end

# app/models/user.rb
class User < ApplicationRecord
  validates :email,
    presence: true,
    format: { with: URI::MailTo::EMAIL_REGEXP },
    uniqueness: { case_sensitive: false },
    mailbeam: true  # our custom validator
end

# spec/validators/mailbeam_validator_spec.rb
RSpec.describe MailbeamValidator do
  let(:user) { build(:user, email: email) }

  before do
    stub_request(:post, 'https://api.mailbeam.dev/v1/verify')
      .to_return(status: 200, body: response_body.to_json)
  end

  context 'with a valid email' do
    let(:email) { 'user@example.com' }
    let(:response_body) { { valid: true, score: 94, reason: nil } }

    it { expect(user).to be_valid }
  end

  context 'with a disposable email' do
    let(:email) { 'temp@mailinator.com' }
    let(:response_body) { { valid: false, score: 2, reason: 'disposable_domain' } }

    it 'adds an error' do
      user.valid?
      expect(user.errors[:email]).to include('must not be a temporary email address')
    end
  end

  context 'when Mailbeam API is down' do
    let(:email) { 'user@example.com' }
    before { stub_request(:post, anything).to_raise(Faraday::Error) }

    it 'fails open (no error added)' do
      expect(user).to be_valid
    end
  end
end