PHP SDK

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

EmailVerify 官方 PHP SDK 提供了易于使用的邮箱验证接口,支持 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',
    ]
);

Environment 配置

# .env
EMAILVERIFY_API_KEY=your_api_key_here

单个验证

基本验证

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

echo "邮箱: " . $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;        // '有效'、'无效'、'未知'、'接受所有'
    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";
}

使用 Webhook

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

使用 Facade

use EmailVerify\Laravel\Facades\EmailVerify;

// 单个验证
$result = EmailVerify::verify('user@example.com');

// 批量验证
$job = EmailVerify::verifyBulk($emails);

// 检查额度
$credits = EmailVerify::getCredits();

依赖 Injection

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' => '无效的邮箱地址']);
        }

        // 继续注册...
    }
}

验证规则

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

表单请求

<?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' => '请提供有效的邮箱地址。',
        ];
    }
}

队列验证

<?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);

中间件

<?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' => '无效的邮箱地址'
                ], 422);
            }

            if ($result->result->disposable) {
                return response()->json([
                    'error' => '不允许使用一次性邮箱'
                ], 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);

        // 拒绝无效邮箱
        if ($result->status === 'invalid') {
            return [
                'valid' => false,
                'reason' => 'invalid_email',
                'message' => '此邮箱地址无效',
            ];
        }

        // 拒绝一次性邮箱
        if ($result->result->disposable) {
            return [
                'valid' => false,
                'reason' => 'disposable',
                'message' => '请使用永久邮箱地址',
            ];
        }

        // 警告角色邮箱
        if ($result->result->role) {
            return [
                'valid' => true,
                'warning' => 'role_based',
                'message' => '建议使用个人邮箱',
            ];
        }

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

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

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

批量列表清理

<?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' => '邮箱是必需的']);
    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

安装

要求

快速开始

配置

客户端选项

Environment 配置

单个验证

基本验证

带选项的验证

响应结构

批量验证

提交任务

检查状态

获取结果

使用 Webhook

额度管理

错误处理

异常类型

Laravel 集成

服务提供者

配置

使用 Facade

依赖 Injection

验证规则

表单请求

队列验证

中间件

完整示例

注册验证

批量列表清理

API 端点

最佳实践

1. 缓存结果

2. 优雅地处理错误

下一步

API 参考

Laravel 集成

On this page