README

Official PHP client for the EmailSherlock email-verification API. Verify one address or a batch over HTTPS with an API key. Get an API key at https://emailsherlock.com/api. Want to try a single address by hand first? The free email verification tool runs the same checks in the browser.

PHP 8.1+. Requires ext-curl and ext-json. No other dependencies.

Install

composer require emailsherlock/client

Quick start

<?php
use Emailsherlock\Client;

// reads the key from the environment, never hard-code it
$es = new Client(getenv('ES_KEY'));

$result = $es->verify->single(['email' => 'jane@acme.com']);

echo $result->result; // 'valid'
echo $result->score;  // 0.95

Called with null, new Client(null) reads ES_KEY (or EMAILSHERLOCK_API_KEY) from the environment.

Batch

Up to 100 addresses per call. Each item is either a VerifyResult or a BatchItemError:

use Emailsherlock\VerifyResult;

$batch = $es->verify->batch(['emails' => ['jane@acme.com', 'sales@acme.com']]);

foreach ($batch->results as $item) {
    if ($item instanceof VerifyResult) {
        echo "{$item->email}: {$item->result}\n";
    } else { // BatchItemError
        echo "{$item->email} failed: {$item->error}\n";
    }
}

The result object

VerifyResult mirrors the API JSON:

The fields from deliverable down are null on responses from API servers that do not send them yet. Tolerate null rather than relying on presence.

The domain object

VerifyDomain describes the domain behind the address:

Credits and rate limits

After every call:

$es->creditsRemaining;  // e.g. 41.0
$es->rateLimit;         // ['limit' => 60, 'remaining' => 59, 'reset' => 1700000000]

Errors

Every failure throws a subclass of Emailsherlock\Exception\EmailsherlockException:

Each exception exposes ->statusCode and ->errorCode (the API's string code, e.g. rate_limit_exceeded).

use Emailsherlock\Exception\RateLimitException;

try {
    $es->verify->single(['email' => 'jane@acme.com']);
} catch (RateLimitException $e) {
    echo "retry after {$e->retryAfter}s";
}

Options

new Client(
    apiKey: getenv('ES_KEY'),
    baseUrl: 'https://api.emailsherlock.com', // default
    timeout: 30.0,                             // default
);

License

MIT. Full API reference: https://emailsherlock.com/api/docs