Trueform PHP SDK

The official PHP client for the Trueform email validation API. Validate email format, disposable and freemail providers, common domain typos, and mail routing without an API key.

Documentation | API reference | Packagist | Changelog | Issues

Features

• Immutable, typed validation results
• Built-in cURL transport and PSR-18 support
• Retries for connection failures, timeouts, rate limits, and server errors
• Auto-discovered Laravel 12-13 provider and validation rules
• Client-level and per-request configuration

Install

composer require trueform/trueform

The SDK supports PHP 8.1 and newer and does not require an API key. The default transport requires the cURL extension. Applications without cURL can inject any PSR-18 client instead.

Quickstart

<?php

use Trueform\Client;

$trueform = new Client();
$validation = $trueform->validations->create('user@example.com');

if ($validation->isDeliverable()) {
    echo 'Email looks good';
}

Handle validation results

Validation results are immutable objects with public readonly properties and predicate methods:

if (null !== $validation->didYouMean) {
    echo "Did you mean {$validation->didYouMean}?";
}

if ($validation->isDisposable()) {
    echo 'Ask for a permanent email address';
}

Available values and methods:

• email
• isValidFormat and isValidFormat()
• isFreemail and isFreemail()
• isDisposable and isDisposable()
• hasMxRecords and hasMxRecords()
• didYouMean
• isDeliverable and isDeliverable()
• toArray()

isDeliverable() is a domain-level verdict. It does not prove that a specific mailbox exists.

Configure the client

Timeout values and retry delays use seconds:

$trueform = new Client(
    timeout: 5,
    maxRetries: 2,
);

Override options for one request:

$validation = $trueform->validations->create(
    'user@example.com',
    timeout: 2,
    maxRetries: 0,
);

The client retries connection failures, timeouts, rate limits, and server errors. A Retry-After response header controls the delay when present. Use baseUrl: to point the client at a different Trueform-compatible endpoint.

Laravel

Laravel discovers the service provider automatically. Use either validation rule in a form request or controller:

use Trueform\Laravel\Rules\DeliverableEmail;
use Trueform\Laravel\Rules\NotDisposableEmail;

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

The rules fail open for rate limits, server errors, timeouts, and connection failures. Invalid requests fail validation, while malformed responses and configuration errors are rethrown.

Configure the Laravel client with environment variables:

TRUEFORM_BASE_URL=https://api.trueform.cloud
TRUEFORM_TIMEOUT=10
TRUEFORM_MAX_RETRIES=2

Publish the configuration file only when you need to customize it:

php artisan vendor:publish --tag=trueform-config

The configured Trueform\Client is available through Laravel's container for constructor injection.

PSR-18

Use an existing PSR-18 client and PSR-17 factories instead of the built-in cURL transport:

use Trueform\Client;
use Trueform\Transport\Psr18Transport;

$transport = new Psr18Transport(
    client: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$trueform = new Client(transport: $transport);

PSR-18 does not define request timeouts or a timeout-specific exception. Configure timeouts on the injected HTTP client; client and network failures are exposed as ConnectionException and remain retryable.

Symfony

The client can be injected into a custom Symfony ConstraintValidator:

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;
use Trueform\Client;
use Trueform\Exception\TrueformException;

final class DeliverableEmailValidator extends ConstraintValidator
{
    public function __construct(private readonly Client $trueform)
    {
    }

    public function validate(mixed $value, Constraint $constraint): void
    {
        if (!is_string($value) || '' === $value) {
            return;
        }

        try {
            $validation = $this->trueform->validations->create($value);
        } catch (TrueformException $exception) {
            if ($exception->isTransient()) {
                return;
            }

            throw $exception;
        }

        if (!$validation->isDeliverable()) {
            $this->context->buildViolation('This email address is not deliverable.')->addViolation();
        }
    }
}

Errors

use Trueform\Exception\InvalidRequestException;
use Trueform\Exception\RateLimitException;

try {
    $validation = $trueform->validations->create('user@example.com');
} catch (RateLimitException $exception) {
    echo "Retry after {$exception->retryAfter} seconds";
} catch (InvalidRequestException $exception) {
    echo $exception->getMessage();
}

Exported exceptions:

• TrueformException
• ConfigurationException
• ApiException
• InvalidRequestException
• RateLimitException
• ConnectionException
• TimeoutException

Exceptions expose errorCode, status, requestId, and retryAfter when available. Use isTransient() to distinguish temporary failures.

Development

composer install
composer check

Read the contributing guide before opening a pull request. Report vulnerabilities through the process in the security policy.

Trueform SDKs

Platform	Registry	Source
Node.js	trueform-node on npm	GitHub
PHP	trueform/trueform on Packagist	GitHub
Ruby	trueform on RubyGems	GitHub
Python	trueform-cloud on PyPI	GitHub

License

MIT. See the license.