Verifica delle email in PHP

Questo tutorial copre l'integrazione di Mailbeam in qualsiasi applicazione PHP, non solo in Laravel. Vedrai due approcci: con il client HTTP Guzzle (consigliato) e con cURL puro e semplice (senza dipendenze).

Prerequisiti

PHP 8.1 o successivo
Composer (facoltativo, per Guzzle)
Una chiave API di Mailbeam (iscriviti gratis)

Preparazione

Aggiungi la tua chiave API al tuo ambiente:

# .env o configurazione d'ambiente
MAILBEAM_KEY=mb_live_xxxxxxxxxxxxxxxxxxxx

Opzione A — Con Guzzle

composer require guzzlehttp/guzzle

<?php
// src/Services/MailbeamService.php

namespace App\Services;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class MailbeamService
{
    private Client $client;

    public function __construct()
    {
        $this->client = new Client([
            'base_uri' => 'https://api.mailbeam.dev',
            'timeout'  => 5.0,
            'headers'  => [
                'Authorization' => 'Bearer ' . $_ENV['MAILBEAM_KEY'],
                'Content-Type'  => 'application/json',
            ],
        ]);
    }

    /**
     * Restituisce ['valid' => bool, 'score' => int, 'reason' => string|null]
     * oppure null in caso di errore dell'API (chi chiama deve lasciar passare).
     */
    public function verify(string $email): ?array
    {
        try {
            $response = $this->client->post('/v1/verify', [
                'json' => ['email' => $email],
            ]);

            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            error_log('[Mailbeam] verifica fallita: ' . $e->getMessage());
            return null;
        }
    }
}

Opzione B — cURL puro (senza dipendenze)

<?php
function mailbeam_verify(string $email): ?array
{
    $apiKey = $_ENV['MAILBEAM_KEY'] ?? '';
    $payload = json_encode(['email' => $email]);

    $ch = curl_init('https://api.mailbeam.dev/v1/verify');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_TIMEOUT        => 5,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
        ],
    ]);

    $body  = curl_exec($ch);
    $error = curl_error($ch);
    curl_close($ch);

    if ($error || !$body) {
        error_log('[Mailbeam] errore di cURL: ' . $error);
        return null; // lascia passare
    }

    return json_decode($body, true);
}

Usare la verifica nella tua registrazione

<?php
// signup.php

$email    = trim(strtolower($_POST['email'] ?? ''));
$password = $_POST['password'] ?? '';

if (!$email || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
    http_response_code(422);
    echo json_encode(['error' => 'Inserisci un indirizzo email valido.']);
    exit;
}

// Verifica con Mailbeam
$service = new MailbeamService();
$result  = $service->verify($email);

$valid = $result['valid'] ?? true;  // lascia passare se $result è null
$score = $result['score'] ?? 100;
$reason = $result['reason'] ?? null;

if ($result !== null && (!$valid || $score < 60)) {
    $message = match ($reason) {
        'disposable_domain' => 'Usa un indirizzo email permanente.',
        'no_mx_records'     => 'Questo dominio non può ricevere posta.',
        default             => 'Inserisci un indirizzo email valido.',
    };
    http_response_code(422);
    echo json_encode(['error' => $message, 'code' => $reason]);
    exit;
}

// Prosegui con la creazione dell'utente...
create_user($email, $password);
echo json_encode(['success' => true]);

Aggiungere uno strato di cache

<?php
function verify_with_cache(string $email, MailbeamService $service): ?array
{
    $key = 'mailbeam_' . md5(strtolower(trim($email)));

    // APCu (un solo server)
    if (apcu_exists($key)) {
        return apcu_fetch($key);
    }

    $result = $service->verify($email);

    if ($result !== null) {
        apcu_store($key, $result, 3600); // in cache per 1 ora
    }

    return $result;
}

Buone pratiche

Lascia sempre passare in caso di errore (restituisci null, non ['valid' => false])
Normalizza l'email con strtolower(trim($email)) prima di verificare e di mettere in cache
Usa FILTER_VALIDATE_EMAIL prima di chiamare Mailbeam, per intercettare a costo zero gli errori di sintassi evidenti
Metti un tempo di attesa massimo di 5 secondi sulla richiesta HTTP