PHP SDK

Official PHP SDK for the Truelist email validation API.

Installation

composer require truelist/truelist-php

Requires PHP 8.1+ and Guzzle 7.0+.

Quick start

use TruelistTruelist;

$client = new Truelist('your-api-key');
$result = $client->validate('user@example.com');

if ($result->isValid()) {
    echo "Email is valid!";
}

Configuration

$client = new Truelist('your-api-key', [
    'base_url'       => 'https://api.truelist.io',
    'timeout'        => 10,
    'max_retries'    => 2,
    'raise_on_error' => false,
]);

Result methods

$result->email;       // 'user@example.com'
$result->state;       // 'ok', 'email_invalid', 'accept_all', 'unknown'
$result->subState;    // 'email_ok', 'is_disposable', 'is_role', ...
$result->suggestion;  // null or correction
$result->domain;
$result->verifiedAt;

Predicates: isValid(), isInvalid(), isAcceptAll(), isUnknown(), isDisposable(), isRole()

Error handling

Auth errors (401) always throw AuthenticationException. When raise_on_error is false (default), transient errors return an unknown result with isError() === true.

use TruelistExceptionsAuthenticationException;
use TruelistExceptionsRateLimitException;

try {
    $result = $client->validate('user@example.com');
} catch (AuthenticationException $e) {
    // Bad API key
} catch (RateLimitException $e) {
    // Rate limited
}

Laravel integration

composer require truelist/laravel
php artisan vendor:publish --tag=truelist-config

Add your API key to .env:

TRUELIST_API_KEY=your_api_key_here

Validation rule

use TruelistRulesDeliverable;

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

// or shorthand:
$request->validate([
    'email' => ['required', 'email', 'deliverable'],
]);

Facade

use TruelistFacadesTruelist;

$result = Truelist::validate('user@example.com');

Caching

TRUELIST_CACHE_ENABLED=true
TRUELIST_CACHE_TTL=3600

Uses Laravel’s default cache driver. Unknown/error results are never cached.

Config (config/truelist.php)

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12

Package links