PHPackages                             truelist/laravel - 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. [Mail & Notifications](/categories/mail)
4. /
5. truelist/laravel

ActiveLibrary[Mail & Notifications](/categories/mail)

truelist/laravel
================

Laravel integration for Truelist.io email validation

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

Since Feb 21Pushed 4mo agoCompare

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

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

truelist/laravel
================

[](#truelistlaravel)

[![Free tier](https://camo.githubusercontent.com/6917bb3e9ecaa2f2d7134be8fec205225f650aba12ae6cc47b4c6955a6f7b672/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f667265655f706c616e2d3130305f76616c69646174696f6e732d3441374335393f7374796c653d666c61742d737175617265)](https://truelist.io/pricing)Email validation for Laravel, powered by [Truelist.io](https://truelist.io).

[![CI](https://github.com/Truelist-io-Email-Validation/truelist-laravel/actions/workflows/ci.yml/badge.svg)](https://github.com/Truelist-io-Email-Validation/truelist-laravel/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/9b5b341fd39d3487991b9fe0ae07bccc83334435a0a1fcf8d0c1e9e42e2e9d23/68747470733a2f2f706f7365722e707567782e6f72672f747275656c6973742f6c61726176656c2f762f737461626c65)](https://packagist.org/packages/truelist/laravel)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

Validate email deliverability in your Laravel forms with a single line:

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

Truelist checks whether an email address actually exists and can receive mail, catching typos, disposable addresses, and invalid mailboxes before they hit your database.

> **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-laravel)

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

[](#installation)

```
composer require truelist/laravel
```

The service provider is auto-discovered. To publish the config file:

```
php artisan vendor:publish --tag=truelist-config
```

Add your API key to `.env`:

```
TRUELIST_API_KEY=your_api_key_here

```

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

[](#quick-start)

```
use Truelist\Rules\Deliverable;

// In a FormRequest or controller:
$request->validate([
    'email' => ['required', 'email', new Deliverable],
]);
```

That's it. Invalid emails will now fail validation with a clear error message.

Configuration
-------------

[](#configuration)

Publish the config file to customize settings:

```
php artisan vendor:publish --tag=truelist-config
```

This creates `config/truelist.php`:

```
return [
    // Your Truelist API key (required).
    'api_key' => env('TRUELIST_API_KEY'),

    // API base URL. Change only for testing or proxying.
    'base_url' => env('TRUELIST_BASE_URL', 'https://api.truelist.io'),

    // Request timeout in seconds.
    'timeout' => env('TRUELIST_TIMEOUT', 10),

    // When true, raises exceptions on API failures.
    // When false (default), returns "unknown" on errors (fail open).
    // Note: Auth errors (401) always throw regardless of this setting.
    'raise_on_error' => env('TRUELIST_RAISE_ON_ERROR', false),

    // Cache settings to avoid redundant API calls.
    'cache' => [
        'enabled' => env('TRUELIST_CACHE_ENABLED', false),
        'ttl'     => env('TRUELIST_CACHE_TTL', 3600),
        'prefix'  => 'truelist:',
    ],
];
```

Validation Rule
---------------

[](#validation-rule)

### Using the rule object (recommended)

[](#using-the-rule-object-recommended)

```
use Truelist\Rules\Deliverable;

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

### Using the string shorthand

[](#using-the-string-shorthand)

```
$request->validate([
    'email' => ['required', 'email', 'deliverable'],
]);
```

### Behavior on errors

[](#behavior-on-errors)

The validation rule **fails open** by design. If the Truelist API is unreachable (timeout, 500, rate limit), the email passes validation so your forms keep working.

Authentication errors (invalid API key) always throw an exception -- you want to know immediately if your credentials are wrong.

Using the Client Directly
-------------------------

[](#using-the-client-directly)

```
use Truelist\TruelistClient;

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

$result->state;       // "ok", "email_invalid", "accept_all", or "unknown"
$result->subState;    // "email_ok", "is_disposable", "is_role", etc.
$result->isValid();   // true when state is "ok"
$result->isInvalid(); // true when state is "email_invalid"
$result->isAcceptAll(); // true when state is "accept_all"
$result->isUnknown(); // true when state is "unknown"

$result->domain;      // Domain part of the email address
$result->canonical;   // Local part of the email address
$result->mxRecord;    // MX record for the domain, if available
$result->firstName;   // First name, if available
$result->lastName;    // Last name, if available
$result->verifiedAt;  // Timestamp of verification
$result->suggestion;  // Suggested correction, if available

$result->isDisposable(); // true when sub-state is "is_disposable"
$result->isRole();       // true when sub-state is "is_role"
```

Facade Usage
------------

[](#facade-usage)

```
use Truelist\Facades\Truelist;

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

if ($result->isValid()) {
    // Good to go
}
```

States
------

[](#states)

StateMeaning`ok`Email is valid and deliverable`email_invalid`Email is invalid or undeliverable`accept_all`Domain accepts all emails (risky)`unknown`Could not determine statusSub-states
----------

[](#sub-states)

Sub-stateMeaning`email_ok`Email is valid and deliverable`is_disposable`Disposable/temporary email`is_role`Role-based address (info@, admin@)`accept_all`Domain accepts all emails`failed_mx_check`Domain has no mail server`failed_spam_trap`Known spam trap address`failed_no_mailbox`Mailbox does not exist`failed_greylisted`Server temporarily rejected (greylisting)`failed_syntax_check`Email format is invalid`unknown`Could not determine statusCaching
-------

[](#caching)

Enable caching to avoid redundant API calls for recently validated emails:

```
TRUELIST_CACHE_ENABLED=true
TRUELIST_CACHE_TTL=3600
```

Caching uses Laravel's default cache driver. Only successful results are cached -- unknowns and errors are never cached, so a subsequent request can get the real result.

The cache key is based on the lowercase, trimmed email address.

Error Handling
--------------

[](#error-handling)

By default, API errors (timeouts, rate limits, server errors) return an `unknown` result with `isError()` returning `true`. This prevents your forms from breaking when the API is unreachable.

To raise exceptions instead:

```
TRUELIST_RAISE_ON_ERROR=true
```

Exception classes:

ExceptionTrigger`Truelist\Exceptions\TruelistException`Base exception class`Truelist\Exceptions\AuthenticationException`Invalid API key (401) -- **always thrown**`Truelist\Exceptions\RateLimitException`Rate limit exceeded (429)`Truelist\Exceptions\ApiException`Other API errors (500, timeouts, etc.)Testing
-------

[](#testing)

Mock the HTTP client in your tests to avoid real API calls:

```
use Illuminate\Support\Facades\Http;

Http::fake([
    'api.truelist.io/*' => Http::response([
        'emails' => [[
            'address' => 'user@example.com',
            'domain' => 'example.com',
            'canonical' => 'user',
            'mx_record' => null,
            'first_name' => null,
            'last_name' => null,
            'email_state' => 'ok',
            'email_sub_state' => 'email_ok',
            'verified_at' => '2026-02-21T10:00:00.000Z',
            'did_you_mean' => null,
        ]],
    ]),
]);
```

Or mock the client directly:

```
use Truelist\TruelistClient;
use Truelist\ValidationResult;

$this->mock(TruelistClient::class, function ($mock) {
    $mock->shouldReceive('validate')
        ->andReturn(new ValidationResult(
            email: 'user@example.com',
            state: 'ok',
        ));
});
```

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

[](#requirements)

- PHP >= 8.1
- Laravel 10, 11, or 12

Development
-----------

[](#development)

```
git clone https://github.com/Truelist-io-Email-Validation/truelist-laravel.git
cd truelist-laravel
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-laravel) to get your API key. The free plan includes 100 validations and 10 enhanced credits — no credit card required.

License
-------

[](#license)

Released under the [MIT License](LICENSE).

###  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 (6 commits)")

---

Tags

email-validationlaravellaravel-packagephptruelistvalidationlaravelvalidationemailemail validationdeliverabilitytruelist

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77922.3M186](/packages/laravel-mcp)[propaganistas/laravel-disposable-email

Disposable email validator

6023.0M7](/packages/propaganistas-laravel-disposable-email)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[erag/laravel-disposable-email

A Laravel package to detect and block disposable email addresses.

254168.5k](/packages/erag-laravel-disposable-email)[sandermuller/laravel-fluent-validation

Fluent validation rule builders for Laravel

20720.5k4](/packages/sandermuller-laravel-fluent-validation)[api-platform/laravel

API Platform support for Laravel

58174.6k17](/packages/api-platform-laravel)

PHPackages © 2026

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