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

環境配置

# .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 Key\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();

依賴注入

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

安裝

需求

快速入門

配置

客戶端選項

環境配置

單一驗證

基本驗證

帶選項的驗證

回應結構

批量驗證

提交任務

檢查狀態

獲取結果

使用 Webhook

額度管理

錯誤處理

異常類型

Laravel 整合

服務提供者

配置

使用 Facade

依賴注入

驗證規則

表單請求

佇列驗證

中介軟體

完整範例

註冊驗證

批量列表清理

API 端點

最佳實踐

1. 快取結果

2. 優雅地處理錯誤

下一步

API 參考文件

Laravel 整合

On this page