Verifica delle email in Ruby on Rails

Questo tutorial aggiunge la verifica delle email a un'applicazione Rails con un ActiveModel::EachValidator tuo. Si aggancia alla catena di validazione standard di Rails, quindi funziona con valid?, save! e create!.

Prerequisiti

Ruby 3.0+, Rails 7+
Una chiave API di Mailbeam (iscriviti gratis)

Preparazione

# Gemfile — usa net/http (incluso) oppure faraday
gem 'faraday'  # facoltativo, ma più pulito per le chiamate a un'API

Aggiungi questo a config/credentials.yml.enc (con rails credentials:edit):

mailbeam:
  key: mb_live_xxxxxxxxxxxxxxxxxxxx

Crea il validatore

# 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? # errore dell'API: lascia passare

    unless result['valid'] && result['score'].to_i >= MIN_SCORE
      reason = result['reason']
      message = case reason
                when 'disposable_domain' then 'non può essere un indirizzo email temporaneo'
                when 'no_mx_records'     then 'ha un dominio che non può ricevere posta'
                when 'smtp_rejected'     then 'non sembra esistere'
                else 'non è un indirizzo email valido'
                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] verifica fallita: #{e.message}"
    nil # lascia passare
  end
end

Aggiungilo al tuo modello User

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

Test con RSpec

# 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 'con un indirizzo valido' do
    let(:email) { 'user@example.com' }
    let(:response_body) { { valid: true, score: 94, reason: nil } }

    it { expect(user).to be_valid }
  end

  context 'con un indirizzo usa e getta' do
    let(:email) { 'temp@mailinator.com' }
    let(:response_body) { { valid: false, score: 2, reason: 'disposable_domain' } }

    it 'aggiunge un errore' do
      user.valid?
      expect(user.errors[:email]).to include('non può essere un indirizzo email temporaneo')
    end
  end

  context "quando l'API di Mailbeam non risponde" do
    let(:email) { 'user@example.com' }
    before { stub_request(:post, anything).to_raise(Faraday::Error) }

    it 'lascia passare (non aggiunge alcun errore)' do
      expect(user).to be_valid
    end
  end
end