A framework-agnostic PSR-18 client for any PHP application.
Using Laravel? Reach for the Laravel package instead — it adds a facade and a Deliverable validation rule. This framework-agnostic client works everywhere else.
Require the package with Composer. It targets PHP 8.2+ and speaks PSR-18, so it works with any HTTP client (Guzzle is used by default).
composer require bounceshift/bounceshift-phpConstruct a client with your API key and organization ID (your team ID), then call validate(). You get back a typed result with the status, a 0–100 confidence score, and helper flags:
use BounceShift\Client;
$client = new Client('YOUR_API_KEY', 'YOUR_ORG_ID');
$result = $client->validate('[email protected]');
$result->status->value; // 'valid', 'catch_all', 'unknown', 'invalid', ...
$result->confidence; // 0-100
$result->isSafeToSend(); // true for 'valid' or 'catch_all'
$result->smtpValid; // ?bool — null when inconclusive
$result->fromCache; // bool — no credit is spent on a cache hit
$result->creditsUsed; // intTune the timeout and retry behavior when constructing the client:
$client = new Client('YOUR_API_KEY', 'YOUR_ORG_ID', [
'timeout' => 10, // seconds
'retries' => 2, // auto-retry on 429 / 5xx with a clamped backoff
]);Non-success responses raise typed exceptions you can catch individually. See the full list on the status & error codes reference.
use BounceShift\Exceptions\InsufficientCreditsException;
use BounceShift\Exceptions\RateLimitException;
use BounceShift\Exceptions\BounceShiftException;
try {
$result = $client->validate($email);
} catch (InsufficientCreditsException $e) {
// 402 — top up credits
} catch (RateLimitException $e) {
// 429 — back off for $e->retryAfter seconds
} catch (BounceShiftException $e) {
// network/timeout or any other API error
}Related terms
Get 100 free validations to test our service. No credit card required.
Start Free Trial