PHPackages                             truelist/truelist-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. truelist/truelist-php

ActiveLibrary[HTTP & Networking](/categories/http)

truelist/truelist-php
=====================

PHP SDK for the Truelist email validation API

v0.1.0(5mo ago)00MITPHPPHP ^8.1CI passing

Since Feb 21Pushed 4mo agoCompare

[ Source](https://github.com/Truelist-Labs/truelist-php)[ Packagist](https://packagist.org/packages/truelist/truelist-php)[ Docs](https://truelist.io)[ RSS](/packages/truelist-truelist-php/feed)WikiDiscussions development Synced 3w ago

READMEChangelogDependencies (2)Versions (3)Used By (0)

Truelist PHP SDK
================

[](#truelist-php-sdk)

[![Free tier](https://camo.githubusercontent.com/6917bb3e9ecaa2f2d7134be8fec205225f650aba12ae6cc47b4c6955a6f7b672/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f667265655f706c616e2d3130305f76616c69646174696f6e732d3441374335393f7374796c653d666c61742d737175617265)](https://truelist.io/pricing)PHP SDK for the [Truelist](https://truelist.io) email validation API.

[![CI](https://github.com/Truelist-io-Email-Validation/truelist-php/actions/workflows/ci.yml/badge.svg)](https://github.com/Truelist-io-Email-Validation/truelist-php/actions/workflows/ci.yml)

Requirements
------------

[](#requirements)

- PHP 8.1+
- Guzzle 7.0+

> **Start free** — 100 validations + 10 enhanced credits, no credit card required. [Get your API key →](https://app.truelist.io/signup?utm_source=github&utm_medium=readme&utm_campaign=free-plan&utm_content=truelist-php)

Installation
------------

[](#installation)

```
composer require truelist/truelist-php
```

Quick Start
-----------

[](#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
-------------

[](#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
]);
```

OptionDefaultDescription`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
-------

[](#methods)

### `validate(string $email): ValidationResult`

[](#validatestring-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`

[](#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-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
---------------

[](#response-states)

StateDescription`ok`Email is valid and deliverable`email_invalid`Email is not deliverable`accept_all`Domain accepts all emails (catch-all)`unknown`Could not determine validityResponse Sub-States
-------------------

[](#response-sub-states)

Sub-StateDescription`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 determineError Handling
--------------

[](#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

[](#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

[](#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

[](#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
-------

[](#testing)

```
composer install
vendor/bin/phpunit
```

Getting Started
---------------

[](#getting-started)

Sign up for a [free Truelist account](https://app.truelist.io/signup?utm_source=github&utm_medium=readme&utm_campaign=free-plan&utm_content=truelist-php) to get your API key. The free plan includes 100 validations and 10 enhanced credits — no credit card required.

License
-------

[](#license)

MIT

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance73

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

153d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/88a5261fb5f1d25e9504bd446937ab47bf3358408b3d18da82d631fc5eed033b?d=identicon)[Truelist](/maintainers/Truelist)

---

Top Contributors

[![coreyhaines31](https://avatars.githubusercontent.com/u/34802794?v=4)](https://github.com/coreyhaines31 "coreyhaines31 (7 commits)")

---

Tags

email-validationguzzlephpsdktruelistvalidationemailemail-verificationtruelist

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/truelist-truelist-php/health.svg)

```
[![Health](https://phpackages.com/badges/truelist-truelist-php/health.svg)](https://phpackages.com/packages/truelist-truelist-php)
```

###  Alternatives

[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k46](/packages/neuron-core-neuron-ai)[illuminate/http

The Illuminate Http package.

11937.9M7.5k](/packages/illuminate-http)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)[ellaisys/aws-cognito

Laravel Authentication using AWS Cognito (Web and API)

121256.9k1](/packages/ellaisys-aws-cognito)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)