README

PHP SDK for the Truelist email validation API.

Requirements

PHP 8.1+
Guzzle 7.0+

Start free — 100 validations + 10 enhanced credits, no credit card required. Get your API key →

Installation

composer require truelist/truelist-php

Quick Start

use Truelist\Truelist;

$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', // API base URL
    'timeout'        => 10,                         // Request timeout in seconds
    'max_retries'    => 2,                          // Retries on 429/5xx errors
    'raise_on_error' => false,                      // Throw on transient errors
]);

Option	Default	Description
`base_url`	`https://api.truelist.io`	API base URL
`timeout`	`10`	Request timeout in seconds
`max_retries`	`2`	Number of retries on 429/5xx errors (with exponential backoff)
`raise_on_error`	`false`	When `false`, transient errors return an unknown result. When `true`, they throw.

Methods

`validate(string $email): ValidationResult`

Validates an email address. Sends a POST to /api/v1/verify_inline with the email as a query parameter.

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

$result->email;       // 'user@example.com'
$result->state;       // 'ok', 'email_invalid', 'accept_all', 'unknown'
$result->subState;    // 'email_ok', 'is_disposable', 'is_role', etc.
$result->suggestion;  // Suggested correction or null
$result->domain;      // 'example.com'
$result->canonical;   // 'user'
$result->mxRecord;    // MX record or null
$result->firstName;   // First name or null
$result->lastName;    // Last name or null
$result->verifiedAt;  // ISO 8601 timestamp or null

`account(): AccountInfo`

Retrieves account information from GET /me.

$account = $client->account();

$account->email;        // 'team@company.com'
$account->name;         // 'Team Lead'
$account->uuid;         // 'a3828d19-...'
$account->timeZone;     // 'America/New_York'
$account->isAdminRole;  // true
$account->accountName;  // 'Company Inc'
$account->paymentPlan;  // 'pro'

Result Predicates

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

// State checks
$result->isValid();       // true if state is 'ok'
$result->isInvalid();     // true if state is 'email_invalid'
$result->isAcceptAll();   // true if state is 'accept_all'
$result->isUnknown();     // true if state is 'unknown'
$result->isError();       // true if result came from a transient error

// Sub-state checks
$result->isRole();        // true if sub-state is 'is_role'
$result->isDisposable();  // true if sub-state is 'is_disposable'

Response States

State	Description
`ok`	Email is valid and deliverable
`email_invalid`	Email is not deliverable
`accept_all`	Domain accepts all emails (catch-all)
`unknown`	Could not determine validity

Response Sub-States

Sub-State	Description
`email_ok`	Email is valid
`is_disposable`	Disposable/temporary email
`is_role`	Role-based address (info@, admin@)
`failed_smtp_check`	SMTP check failed
`unknown_error`	Could not determine

Error Handling

The SDK uses a hierarchy of exceptions:

TruelistException -- base exception
- AuthenticationException -- invalid API key (401). Always thrown, never suppressed.
- RateLimitException -- rate limit exceeded (429)
- ApiException -- server errors (5xx), connection errors

Auth Errors Always Throw

Authentication errors (HTTP 401) always throw an AuthenticationException, regardless of the raise_on_error setting.

use Truelist\Exceptions\AuthenticationException;

try {
    $result = $client->validate('user@example.com');
} catch (AuthenticationException $e) {
    // Invalid API key - always thrown
}

Transient Error Behavior

For transient errors (429, 5xx, timeouts), behavior depends on raise_on_error:

// raise_on_error: false (default)
// Returns a ValidationResult with state='unknown' and error=true
$result = $client->validate('user@example.com');
if ($result->isError()) {
    // Handle transient failure gracefully
}

// raise_on_error: true
// Throws RateLimitException or ApiException
$client = new Truelist('key', ['raise_on_error' => true]);
try {
    $result = $client->validate('user@example.com');
} catch (RateLimitException $e) {
    // 429
} catch (ApiException $e) {
    // 5xx or connection error
}

Retry Behavior

The SDK automatically retries on 429 and 5xx errors with exponential backoff. Configure with max_retries (default: 2). Auth errors (401) are never retried.

Testing

composer install
vendor/bin/phpunit

Getting Started

Sign up for a free Truelist account to get your API key. The free plan includes 100 validations and 10 enhanced credits — no credit card required.

License

MIT

truelist / truelist-php

Maintainers

Package info

Statistics

Security