EmailVerify LogoEmailVerify
SDKs

PHP SDK

PHP email checker SDK. Composer install, verify emails with PHP. Code examples included.

El SDK oficial de EmailVerify para PHP proporciona una interfaz fácil de usar para verificación de correo electrónico con soporte para Laravel.

Instalación

composer require emailverify/php-sdk

Requisitos

  • PHP 8.0 o superior
  • Composer
  • Extensión JSON
  • Extensión cURL

Inicio rápido

<?php

use EmailVerify\Client;

$client = new Client(getenv('EMAILVERIFY_API_KEY'));

$result = $client->verify('user@example.com');
echo "Estado: " . $result->status . "\n";
echo "Puntuación: " . $result->score . "\n";

Configuración

Opciones del cliente

$client = new Client(
    apiKey: getenv('EMAILVERIFY_API_KEY'),
    options: [
        'timeout' => 30,           // Tiempo de espera de solicitud en segundos
        'retries' => 3,            // Número de intentos de reintento
        'base_url' => 'https://api.emailverify.ai',
    ]
);

Configuración de entorno

# .env
EMAILVERIFY_API_KEY=tu_clave_api_aqui

Verificación individual

Verificación básica

$result = $client->verify('user@example.com');

echo "Correo electrónico: " . $result->email . "\n";
echo "Estado: " . $result->status . "\n";
echo "Puntuación: " . $result->score . "\n";
echo "Entregable: " . ($result->result->deliverable ? 'Sí' : 'No') . "\n";
echo "Desechable: " . ($result->result->disposable ? 'Sí' : 'No') . "\n";

Verificación con opciones

$result = $client->verify('user@example.com', [
    'smtp_check' => true,
    'timeout' => 5,
]);

Estructura de respuesta

class VerificationResult {
    public string $email;
    public string $status;        // 'valid', 'invalid', 'unknown', 'accept_all'
    public ResultDetails $result;
    public float $score;
    public ?string $reason;
}

class ResultDetails {
    public ?bool $deliverable;
    public bool $valid_format;
    public bool $valid_domain;
    public bool $valid_mx;
    public bool $disposable;
    public bool $role;
    public bool $catchall;
    public bool $free;
    public ?bool $smtp_valid;
}

Verificación masiva

Enviar trabajo

$emails = [
    'user1@example.com',
    'user2@example.com',
    'user3@example.com',
];

$job = $client->verifyBulk($emails);
echo "ID del trabajo: " . $job->id . "\n";

Verificar estado

$status = $client->getBulkJobStatus($job->id);

echo "Estado: " . $status->status . "\n";
echo "Progreso: " . $status->processed . "/" . $status->total . "\n";
echo "Válidos: " . $status->valid . "\n";
echo "Inválidos: " . $status->invalid . "\n";

Obtener resultados

$results = $client->getBulkJobResults($job->id);

foreach ($results as $result) {
    echo $result->email . ": " . $result->status . "\n";
}

Con webhook

$job = $client->verifyBulk($emails, [
    'webhook_url' => 'https://tu-dominio.com/webhooks/emailverify',
]);

Gestión de créditos

$credits = $client->getCredits();

echo "Disponibles: " . $credits->available . "\n";
echo "Usados: " . $credits->used . "\n";
echo "Total: " . $credits->total . "\n";

Manejo de errores

Tipos de excepciones

use EmailVerify\Client;
use EmailVerify\Exceptions\AuthenticationException;
use EmailVerify\Exceptions\RateLimitException;
use EmailVerify\Exceptions\ValidationException;
use EmailVerify\Exceptions\EmailVerifyException;

try {
    $result = $client->verify('invalid-email');
} catch (AuthenticationException $e) {
    echo "Clave API inválida\n";
} catch (RateLimitException $e) {
    echo "Límite de tasa alcanzado. Reintentar después de " . $e->getRetryAfter() . " segundos\n";
} catch (ValidationException $e) {
    echo "Entrada inválida: " . $e->getMessage() . "\n";
} catch (EmailVerifyException $e) {
    echo "Error de API: " . $e->getMessage() . "\n";
}

Integración con Laravel

Proveedor de servicios

El paquete se descubre automáticamente en Laravel 5.5+. Para versiones anteriores, añadir a config/app.php:

'providers' => [
    EmailVerify\Laravel\EmailVerifyServiceProvider::class,
],

'aliases' => [
    'EmailVerify' => EmailVerify\Laravel\Facades\EmailVerify::class,
],

Configuración

Publicar el archivo de configuración:

php artisan vendor:publish --provider="EmailVerify\Laravel\EmailVerifyServiceProvider"

Archivo de configuración (config/emailverify.php):

<?php

return [
    'api_key' => env('EMAILVERIFY_API_KEY'),
    'timeout' => env('EMAILVERIFY_TIMEOUT', 30),
    'retries' => env('EMAILVERIFY_RETRIES', 3),
];

Usar el Facade

use EmailVerify\Laravel\Facades\EmailVerify;

// Verificación individual
$result = EmailVerify::verify('user@example.com');

// Verificación masiva
$job = EmailVerify::verifyBulk($emails);

// Verificar créditos
$credits = EmailVerify::getCredits();

Inyección de dependencias

use EmailVerify\Client;

class UserController extends Controller
{
    public function __construct(
        private Client $emailVerify
    ) {}

    public function register(Request $request)
    {
        $result = $this->emailVerify->verify($request->email);

        if ($result->status === 'invalid') {
            return back()->withErrors(['email' => 'Dirección de correo electrónico inválida']);
        }

        // Continuar con el registro...
    }
}

Regla de validación

use EmailVerify\Laravel\Rules\ValidEmail;

$request->validate([
    'email' => ['required', 'email', new ValidEmail()],
]);

Regla personalizada con opciones:

use EmailVerify\Laravel\Rules\ValidEmail;

$request->validate([
    'email' => [
        'required',
        'email',
        new ValidEmail([
            'reject_disposable' => true,
            'reject_role' => false,
            'min_score' => 0.7,
        ]),
    ],
]);

Form Request

<?php

namespace App\Http\Requests;

use EmailVerify\Laravel\Rules\ValidEmail;
use Illuminate\Foundation\Http\FormRequest;

class RegisterRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => [
                'required',
                'email',
                'unique:users',
                new ValidEmail([
                    'reject_disposable' => true,
                ]),
            ],
            'password' => ['required', 'min:8', 'confirmed'],
        ];
    }

    public function messages(): array
    {
        return [
            'email.valid_email' => 'Por favor proporciona una dirección de correo electrónico válida.',
        ];
    }
}

Verificación en cola

<?php

namespace App\Jobs;

use EmailVerify\Client;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class VerifyUserEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private int $userId,
        private string $email
    ) {}

    public function handle(Client $client): void
    {
        $result = $client->verify($this->email);

        \App\Models\User::where('id', $this->userId)->update([
            'email_verified' => $result->status === 'valid',
            'email_score' => $result->score,
            'email_disposable' => $result->result->disposable,
        ]);
    }
}

// Despachar
VerifyUserEmail::dispatch($user->id, $user->email);

Middleware

<?php

namespace App\Http\Middleware;

use EmailVerify\Client;
use Closure;
use Illuminate\Http\Request;

class VerifyEmailMiddleware
{
    public function __construct(
        private Client $client
    ) {}

    public function handle(Request $request, Closure $next)
    {
        if ($request->has('email')) {
            $result = $this->client->verify($request->email);

            if ($result->status === 'invalid') {
                return response()->json([
                    'error' => 'Dirección de correo electrónico inválida'
                ], 422);
            }

            if ($result->result->disposable) {
                return response()->json([
                    'error' => 'No se permiten correos electrónicos desechables'
                ], 422);
            }
        }

        return $next($request);
    }
}

Ejemplos completos

Validación de registro

<?php

use EmailVerify\Client;

class EmailValidator
{
    public function __construct(
        private Client $client
    ) {}

    public function validateForRegistration(string $email): array
    {
        $result = $this->client->verify($email);

        // Rechazar correos electrónicos inválidos
        if ($result->status === 'invalid') {
            return [
                'valid' => false,
                'reason' => 'invalid_email',
                'message' => 'Esta dirección de correo electrónico es inválida',
            ];
        }

        // Rechazar correos electrónicos desechables
        if ($result->result->disposable) {
            return [
                'valid' => false,
                'reason' => 'disposable',
                'message' => 'Por favor usa una dirección de correo electrónico permanente',
            ];
        }

        // Advertir sobre correos electrónicos basados en roles
        if ($result->result->role) {
            return [
                'valid' => true,
                'warning' => 'role_based',
                'message' => 'Se recomienda usar un correo electrónico personal',
            ];
        }

        return [
            'valid' => true,
            'score' => $result->score,
        ];
    }
}

// Uso
$validator = new EmailValidator($client);
$validation = $validator->validateForRegistration('user@example.com');

if (!$validation['valid']) {
    echo $validation['message'];
}

Limpieza de lista masiva

<?php

use EmailVerify\Client;

class ListCleaner
{
    public function __construct(
        private Client $client
    ) {}

    public function cleanList(array $emails): array
    {
        // Enviar trabajo masivo
        $job = $this->client->verifyBulk($emails);

        // Sondear para finalización
        while (true) {
            $status = $this->client->getBulkJobStatus($job->id);

            if ($status->status === 'completed') {
                break;
            }

            if ($status->status === 'failed') {
                throw new \Exception('Trabajo masivo fallido');
            }

            sleep(5);
        }

        // Obtener y categorizar resultados
        $results = $this->client->getBulkJobResults($job->id);

        $valid = [];
        $invalid = [];
        $risky = [];

        foreach ($results as $result) {
            if ($result->status === 'invalid') {
                $invalid[] = $result->email;
            } elseif ($result->result->disposable || $result->result->role) {
                $risky[] = $result->email;
            } else {
                $valid[] = $result->email;
            }
        }

        return [
            'valid' => $valid,
            'invalid' => $invalid,
            'risky' => $risky,
            'stats' => [
                'total' => count($emails),
                'valid_count' => count($valid),
                'invalid_count' => count($invalid),
                'risky_count' => count($risky),
            ],
        ];
    }
}

Endpoint de API

<?php
// api/verify.php

header('Content-Type: application/json');

use EmailVerify\Client;

$client = new Client(getenv('EMAILVERIFY_API_KEY'));

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(['error' => 'Método no permitido']);
    exit;
}

$input = json_decode(file_get_contents('php://input'), true);
$email = $input['email'] ?? null;

if (!$email) {
    http_response_code(400);
    echo json_encode(['error' => 'Se requiere correo electrónico']);
    exit;
}

try {
    $result = $client->verify($email);
    echo json_encode([
        'email' => $result->email,
        'status' => $result->status,
        'score' => $result->score,
        'deliverable' => $result->result->deliverable,
    ]);
} catch (\Exception $e) {
    http_response_code(500);
    echo json_encode(['error' => 'Verificación fallida']);
}

Mejores prácticas

1. Cachear resultados

use Illuminate\Support\Facades\Cache;

function verifyWithCache(Client $client, string $email): VerificationResult
{
    $cacheKey = 'email_verification_' . md5($email);

    return Cache::remember($cacheKey, 3600, function () use ($client, $email) {
        return $client->verify($email);
    });
}

2. Manejar errores con gracia

function safeVerify(Client $client, string $email): ?VerificationResult
{
    try {
        return $client->verify($email);
    } catch (RateLimitException $e) {
        Log::warning('Límite de tasa alcanzado', ['retry_after' => $e->getRetryAfter()]);
        return null;
    } catch (EmailVerifyException $e) {
        Log::error('Verificación fallida', ['error' => $e->getMessage()]);
        return null;
    }
}

Próximos pasos

Referencia de API

Documentación detallada de API

Integración con Laravel

Patrones avanzados de Laravel

Go SDK

Go email checker SDK. Install, configure, verify emails with Golang. Code examples included.

Java SDK

Java email checker SDK. Maven/Gradle setup, verify emails with Java. Code examples included.

On this page

InstalaciónRequisitosInicio rápidoConfiguraciónOpciones del clienteConfiguración de entornoVerificación individualVerificación básicaVerificación con opcionesEstructura de respuestaVerificación masivaEnviar trabajoVerificar estadoObtener resultadosCon webhookGestión de créditosManejo de erroresTipos de excepcionesIntegración con LaravelProveedor de serviciosConfiguraciónUsar el FacadeInyección de dependenciasRegla de validaciónForm RequestVerificación en colaMiddlewareEjemplos completosValidación de registroLimpieza de lista masivaEndpoint de APIMejores prácticas1. Cachear resultados2. Manejar errores con graciaPróximos pasos