Vérification d'e-mails en PHP

Ce tutoriel montre comment intégrer Mailbeam à n'importe quelle application PHP, pas seulement à Laravel. Vous verrez deux approches : le client HTTP Guzzle (recommandé) et cURL brut (sans dépendance).

Prérequis

PHP 8.1 ou supérieur
Composer (facultatif, pour Guzzle)
Une clé d'API Mailbeam (inscription gratuite)

Mise en place

Ajoutez votre clé d'API à votre environnement :

# .env ou configuration d'environnement
MAILBEAM_KEY=mb_live_xxxxxxxxxxxxxxxxxxxx

Option A — avec 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',
            ],
        ]);
    }

    /**
     * Renvoie ['valid' => bool, 'score' => int, 'reason' => string|null]
     * ou null en cas d'erreur d'API (à l'appelant d'échouer en mode permissif).
     */
    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] échec de la vérification : ' . $e->getMessage());
            return null;
        }
    }
}

Option B — cURL brut (sans dépendance)

<?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] erreur cURL : ' . $error);
        return null; // échec permissif
    }

    return json_decode($body, true);
}

Utiliser la vérification à l'inscription

<?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' => 'Merci de saisir une adresse e-mail valide.']);
    exit;
}

// Vérification avec Mailbeam
$service = new MailbeamService();
$result  = $service->verify($email);

$valid = $result['valid'] ?? true;  // échec permissif si $result est null
$score = $result['score'] ?? 100;
$reason = $result['reason'] ?? null;

if ($result !== null && (!$valid || $score < 60)) {
    $message = match ($reason) {
        'disposable_domain' => 'Merci d\'utiliser une adresse e-mail permanente.',
        'no_mx_records'     => 'Ce domaine ne peut pas recevoir de courrier.',
        default             => 'Merci de fournir une adresse e-mail valide.',
    };
    http_response_code(422);
    echo json_encode(['error' => $message, 'code' => $reason]);
    exit;
}

// Poursuite de la création du compte…
create_user($email, $password);
echo json_encode(['success' => true]);

Ajouter une couche de cache

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

    // APCu (serveur unique)
    if (apcu_exists($key)) {
        return apcu_fetch($key);
    }

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

    if ($result !== null) {
        apcu_store($key, $result, 3600); // cache d'une heure
    }

    return $result;
}

Bonnes pratiques

Échouez toujours en mode permissif (renvoyez null en cas d'erreur, pas ['valid' => false])
Normalisez l'adresse avec strtolower(trim($email)) avant de vérifier et de mettre en cache
Appelez FILTER_VALIDATE_EMAIL avant Mailbeam, pour attraper à moindre coût les erreurs de syntaxe évidentes
Posez un délai d'expiration de 5 secondes sur la requête HTTP