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

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

bounceshift/bounceshift-php
===========================

Framework-agnostic PHP SDK for the BounceShift email-validation API.

1.0.0(today)01↑2900%1MITPHPPHP ^8.2CI passing

Since Jul 1Pushed todayCompare

[ Source](https://github.com/bounceshift/bounceshift-php)[ Packagist](https://packagist.org/packages/bounceshift/bounceshift-php)[ Docs](https://bounceshift.com)[ RSS](/packages/bounceshift-bounceshift-php/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (2)Used By (1)

BounceShift PHP SDK
===================

[](#bounceshift-php-sdk)

Framework-agnostic PHP client for the [BounceShift](https://bounceshift.com) email-validation API. Given an email address, BounceShift returns a status, a confidence score, and granular deliverability signals so you can protect your sender reputation before you hit send.

- PHP 8.2+
- PSR-18 / PSR-17 based — bring your own HTTP client or let it discover one
- Typed value objects and exceptions
- Automatic retries on `429` and `5xx` (honoring `Retry-After`)

API reference:

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

[](#installation)

```
composer require bounceshift/bounceshift-php
```

The SDK relies on [PSR-18 HTTP Client Discovery](https://docs.php-http.org/en/latest/discovery.html). Guzzle is included as a default implementation; any PSR-18 client works.

Quickstart
----------

[](#quickstart)

```
use BounceShift\Client;

$client = new Client(
    apiKey: 'your-api-key',
    organizationId: 'your-organization-id',
);

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

if ($result->isSafeToSend()) {
    // status is `valid` or `catch_all`
}

echo $result->status->value;   // e.g. "valid"
echo $result->confidence;      // 0-100
```

Both the API key **and** the organization ID are required — they are sent as the `Authorization: Bearer` and `X-Organization-ID` headers respectively.

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

[](#configuration)

```
$client = new Client('your-api-key', 'your-organization-id', [
    'base_url' => 'https://api.bounceshift.com/v1', // default
    'timeout'  => 10,   // seconds
    'retries'  => 2,    // retry attempts on 429 / 5xx
    // Optionally inject your own PSR-18 / PSR-17 implementations:
    // 'http_client'     => $psr18Client,
    // 'request_factory' => $psr17RequestFactory,
    // 'stream_factory'  => $psr17StreamFactory,
]);
```

The result object
-----------------

[](#the-result-object)

`Client::validate()` returns an immutable `BounceShift\ValidationResult`:

PropertyTypeDescription`email``string`The address that was validated.`status``ValidationStatus`The overall verdict (see below).`confidence``int`Confidence score, 0–100.`mxFound``bool`Whether MX records were found.`smtpValid``?bool`SMTP probe result, or `null` if inconclusive.`isDisposable``bool`Disposable/temporary provider.`isCatchAll``bool`Domain accepts all mail.`isRoleAccount``bool`Role address (e.g. `info@`, `support@`).`fromCache``bool`Served from a cached prior result.`creditsUsed``int`Credits consumed by this call.`result``array`Freeform sub-status detail.`ValidationResult::isSafeToSend()` returns `true` only when the status is `valid` or `catch_all`.

### Statuses

[](#statuses)

`BounceShift\ValidationStatus` is a string-backed enum:

`valid`, `invalid`, `risky`, `catch_all`, `unknown`, `disposable`, `spamtrap`, `abuse`, `do_not_mail`.

```
use BounceShift\ValidationStatus;

ValidationStatus::Valid->isSafeToSend();    // true
ValidationStatus::CatchAll->isSafeToSend(); // true
ValidationStatus::Invalid->isSafeToSend();  // false
```

Error handling
--------------

[](#error-handling)

All exceptions extend `BounceShift\Exceptions\BounceShiftException`. API errors extend `ApiException`, which exposes `$statusCode` and `$body`.

```
use BounceShift\Exceptions\AuthenticationException;
use BounceShift\Exceptions\ForbiddenException;
use BounceShift\Exceptions\InsufficientCreditsException;
use BounceShift\Exceptions\RateLimitException;
use BounceShift\Exceptions\ApiException;

try {
    $result = $client->validate('user@example.com');
} catch (AuthenticationException $e) {      // 401
} catch (InsufficientCreditsException $e) { // 402
} catch (ForbiddenException $e) {           // 403
} catch (RateLimitException $e) {           // 429
    $retryAfter = $e->retryAfter;           // ?int seconds
} catch (ApiException $e) {                 // any other non-2xx
    $status = $e->statusCode;
    $body   = $e->body;
}
```

Your API key is never included in exception messages or logs.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT. See [LICENSE](LICENSE).

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 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

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8091592?v=4)[Hussam Abd](/maintainers/Hussam3bd)[@Hussam3bd](https://github.com/Hussam3bd)

---

Top Contributors

[![Hussam3bd](https://avatars.githubusercontent.com/u/8091592?v=4)](https://github.com/Hussam3bd "Hussam3bd (1 commits)")

---

Tags

sdkemailemail validationemail-verificationdeliverabilitybounceshift

###  Code Quality

TestsPest

### Embed Badge

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

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

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k13](/packages/tempest-framework)[chargebee/chargebee-php

ChargeBee API client implementation for PHP

758.5M9](/packages/chargebee-chargebee-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M726](/packages/sylius-sylius)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M407](/packages/drupal-core-recommended)

PHPackages © 2026

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