BillionVerify LogoBillionVerify
SDKs

PHP SDK

SDK de verificación de correos para PHP. Instalación con Composer, soporte para Laravel y ejemplos de código incluidos.

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

Instalación

composer require billionverify/billionverify-php

Requisitos

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

Inicio rápido

<?php

use BillionVerify\Client;

$client = new Client(getenv('BV_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('BV_API_KEY'),
    options: [
        'timeout' => 30,           // Tiempo de espera de solicitud en segundos
        'retries' => 3,            // Número de intentos de reintento
        'base_url' => 'https://api.billionverify.com',
    ]
);

Configuración de entorno

# .env
BV_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', 'catchall'
    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/billionverify',
]);

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 BillionVerify\Client;
use BillionVerify\Exceptions\AuthenticationException;
use BillionVerify\Exceptions\RateLimitException;
use BillionVerify\Exceptions\ValidationException;
use BillionVerify\Exceptions\BillionVerifyException;

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 (BillionVerifyException $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' => [
    BillionVerify\Laravel\BillionVerifyServiceProvider::class,
],

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

Configuración

Publicar el archivo de configuración:

php artisan vendor:publish --provider="BillionVerify\Laravel\BillionVerifyServiceProvider"

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

<?php

return [
    'api_key' => env('BV_API_KEY'),
    'timeout' => env('BV_TIMEOUT', 30),
    'retries' => env('BV_RETRIES', 3),
];

Usar el Facade

use BillionVerify\Laravel\Facades\BillionVerify;

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

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

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

Inyección de dependencias

use BillionVerify\Client;

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

    public function register(Request $request)
    {
        $result = $this->client->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 BillionVerify\Laravel\Rules\ValidEmail;

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

Regla personalizada con opciones:

use BillionVerify\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 BillionVerify\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 BillionVerify\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 BillionVerify\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 BillionVerify\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 BillionVerify\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 BillionVerify\Client;

$client = new Client(getenv('BV_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 (BillionVerifyException $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

SDK de verificación de correos para Go. Instala, configura y verifica correos con Golang. Incluye ejemplos de código.

Java SDK

SDK de verificación de correos para Java. Configuración con Maven/Gradle y ejemplos de código incluidos.

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