PHP SDK

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

Официальный EmailVerify SDK для PHP предоставляет простой в использовании интерфейс для проверки email с поддержкой Laravel.

Установка

composer require emailverify/php-sdk

Требования

PHP 8.0 или выше
Composer
Расширение JSON
Расширение cURL

Быстрый старт

<?php

use EmailVerify\Client;

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

$result = $client->verify('user@example.com');
echo "Статус: " . $result->status . "\n";
echo "Оценка: " . $result->score . "\n";

Конфигурация

Параметры клиента

$client = new Client(
    apiKey: getenv('EMAILVERIFY_API_KEY'),
    options: [
        'timeout' => 30,           // Таймаут запроса в секундах
        'retries' => 3,            // Количество повторных попыток
        'base_url' => 'https://api.emailverify.ai',
    ]
);

Конфигурация окружения

# .env
EMAILVERIFY_API_KEY=your_api_key_here

Единичная проверка

Базовая проверка

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

echo "Email: " . $result->email . "\n";
echo "Статус: " . $result->status . "\n";
echo "Оценка: " . $result->score . "\n";
echo "Доставляемый: " . ($result->result->deliverable ? 'Да' : 'Нет') . "\n";
echo "Одноразовый: " . ($result->result->disposable ? 'Да' : 'Нет') . "\n";

Проверка с параметрами

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

Структура ответа

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;
}

Массовая проверка

Отправка задачи

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

$job = $client->verifyBulk($emails);
echo "ID задачи: " . $job->id . "\n";

Проверка статуса

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

echo "Статус: " . $status->status . "\n";
echo "Прогресс: " . $status->processed . "/" . $status->total . "\n";
echo "Действительных: " . $status->valid . "\n";
echo "Недействительных: " . $status->invalid . "\n";

Получение результатов

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

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

С вебхуком

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

Управление кредитами

$credits = $client->getCredits();

echo "Доступно: " . $credits->available . "\n";
echo "Использовано: " . $credits->used . "\n";
echo "Всего: " . $credits->total . "\n";

Обработка ошибок

Типы исключений

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 "Неверный API-ключ\n";
} catch (RateLimitException $e) {
    echo "Превышен лимит запросов. Повторите через " . $e->getRetryAfter() . " секунд\n";
} catch (ValidationException $e) {
    echo "Неверные входные данные: " . $e->getMessage() . "\n";
} catch (EmailVerifyException $e) {
    echo "Ошибка API: " . $e->getMessage() . "\n";
}

Интеграция с Laravel

Сервис-провайдер

Пакет автоматически обнаруживается в Laravel 5.5+. Для более ранних версий добавьте в config/app.php:

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

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

Конфигурация

Опубликуйте файл конфигурации:

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

Файл конфигурации (config/emailverify.php):

<?php

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

Использование фасада

use EmailVerify\Laravel\Facades\EmailVerify;

// Единичная проверка
$result = EmailVerify::verify('user@example.com');

// Массовая проверка
$job = EmailVerify::verifyBulk($emails);

// Проверка кредитов
$credits = EmailVerify::getCredits();

Внедрение зависимостей

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' => 'Недействительный email-адрес']);
        }

        // Продолжение регистрации...
    }
}

Правило валидации

use EmailVerify\Laravel\Rules\ValidEmail;

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

Пользовательское правило с параметрами:

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' => 'Пожалуйста, укажите действительный email-адрес.',
        ];
    }
}

Проверка через очередь

<?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,
        ]);
    }
}

// Отправка
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' => 'Недействительный email-адрес'
                ], 422);
            }

            if ($result->result->disposable) {
                return response()->json([
                    'error' => 'Одноразовые email-адреса не разрешены'
                ], 422);
            }
        }

        return $next($request);
    }
}

Полные примеры

Валидация при регистрации

<?php

use EmailVerify\Client;

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

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

        // Отклонить недействительные email
        if ($result->status === 'invalid') {
            return [
                'valid' => false,
                'reason' => 'invalid_email',
                'message' => 'Этот email-адрес недействителен',
            ];
        }

        // Отклонить одноразовые email
        if ($result->result->disposable) {
            return [
                'valid' => false,
                'reason' => 'disposable',
                'message' => 'Пожалуйста, используйте постоянный email-адрес',
            ];
        }

        // Предупреждение о ролевых email
        if ($result->result->role) {
            return [
                'valid' => true,
                'warning' => 'role_based',
                'message' => 'Рекомендуется использовать личный email',
            ];
        }

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

// Использование
$validator = new EmailValidator($client);
$validation = $validator->validateForRegistration('user@example.com');

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

Очистка списка email

<?php

use EmailVerify\Client;

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

    public function cleanList(array $emails): array
    {
        // Отправка массовой задачи
        $job = $this->client->verifyBulk($emails);

        // Опрос до завершения
        while (true) {
            $status = $this->client->getBulkJobStatus($job->id);

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

            if ($status->status === 'failed') {
                throw new \Exception('Массовая задача не выполнена');
            }

            sleep(5);
        }

        // Получение и категоризация результатов
        $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),
            ],
        ];
    }
}

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' => 'Метод не разрешён']);
    exit;
}

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

if (!$email) {
    http_response_code(400);
    echo json_encode(['error' => 'Email обязателен']);
    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' => 'Ошибка проверки']);
}

Лучшие практики

1. Кэширование результатов

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. Корректная обработка ошибок

function safeVerify(Client $client, string $email): ?VerificationResult
{
    try {
        return $client->verify($email);
    } catch (RateLimitException $e) {
        Log::warning('Превышен лимит', ['retry_after' => $e->getRetryAfter()]);
        return null;
    } catch (EmailVerifyException $e) {
        Log::error('Ошибка проверки', ['error' => $e->getMessage()]);
        return null;
    }
}

PHP SDK

Установка

Требования

Быстрый старт

Конфигурация

Параметры клиента

Конфигурация окружения

Единичная проверка

Базовая проверка

Проверка с параметрами

Структура ответа

Массовая проверка

Отправка задачи

Проверка статуса

Получение результатов

С вебхуком

Управление кредитами

Обработка ошибок

Типы исключений

Интеграция с Laravel

Сервис-провайдер

Конфигурация

Использование фасада

Внедрение зависимостей

Правило валидации

Form Request

Проверка через очередь

Middleware

Полные примеры

Валидация при регистрации

Очистка списка email

API-эндпоинт

Лучшие практики

1. Кэширование результатов

2. Корректная обработка ошибок

Следующие шаги

Справочник API

Интеграция с Laravel

On this page