bounceshift/laravel

Laravel adapter for the BounceShift email-validation SDK — facade, config, and a Deliverable validation rule.

v1.1.0 2026-07-01 12:25 UTC

Requires

• php: ^8.2
• bounceshift/bounceshift-php: ^1.0
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0

MIT

• BounceShift

• email
• sdk
• laravel
• deliverability
• email-validation
• email-verification
• validation-rule
• bounceshift

README

Laravel adapter for the BounceShift email-validation SDK. It wires the framework-agnostic bounceshift/bounceshift-php client into the container, adds a BounceShift facade, and ships a Deliverable validation rule for forms and requests.

• API reference: https://bounceshift.com/docs/api

Requirements

• PHP ^8.2
• Laravel ^11.0 | ^12.0 | ^13.0

Installation

composer require bounceshift/laravel

The service provider and BounceShift facade are auto-discovered.

Publish the config file (optional):

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

Configuration

Set your credentials in .env:

BOUNCESHIFT_API_KEY=your-api-key
BOUNCESHIFT_ORGANIZATION_ID=your-organization-id

# Optional
BOUNCESHIFT_BASE_URL=https://api.bounceshift.com/v1
BOUNCESHIFT_TIMEOUT=10
BOUNCESHIFT_RETRIES=2

Both BOUNCESHIFT_API_KEY and BOUNCESHIFT_ORGANIZATION_ID are required.

The published config/bounceshift.php:

return [
    'key' => env('BOUNCESHIFT_API_KEY'),
    'organization_id' => env('BOUNCESHIFT_ORGANIZATION_ID'),
    'base_url' => env('BOUNCESHIFT_BASE_URL', \BounceShift\Client::DEFAULT_BASE_URL),
    'timeout' => (int) env('BOUNCESHIFT_TIMEOUT', 10),
    'retries' => (int) env('BOUNCESHIFT_RETRIES', 2),
];

Quickstart

Facade

use BounceShift\Laravel\Facades\BounceShift;

$result = BounceShift::validate('[e-mail]');

$result->status->value;   // 'valid', 'invalid', 'catch_all', ...
$result->confidence;      // 0-100
$result->isSafeToSend();  // true for 'valid' or 'catch_all'
$result->fromCache;       // bool
$result->creditsUsed;     // int

You can also resolve the client directly from the container:

use BounceShift\Client;

$result = app(Client::class)->validate('[e-mail]');

The Deliverable validation rule

Use Deliverable to block undeliverable addresses in form requests and validators:

use BounceShift\Laravel\Rules\Deliverable;

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

Default (lenient) policy — it never blocks on uncertainty:

Status	Result
invalid, disposable, do_not_mail, abuse, spamtrap	❌ fails
valid, catch_all, unknown, risky	✅ passes

If the API is unreachable (network/API outage), the rule fails open and passes, so an outage never blocks your users.

Warning

strict() and minConfidence() can reject real users. On infrastructure where the SMTP probe is throttled — common for Outlook/Hotmail and Gmail — legitimate, deliverable addresses often come back as unknown with low confidence. That is a probe limitation, not a quality signal. For public signup forms, prefer the lenient default, which never blocks on uncertainty. Only reach for strict mode or a confidence floor when you know your unknown rate is low and you would rather lose a few real addresses than accept any risk.

Strict mode

->strict() additionally rejects the uncertain risky and unknown statuses (see the warning above):

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

Confidence threshold

->minConfidence(int) rejects any result scoring below the given threshold (0–100), on top of the always-rejected statuses. It is a graded alternative to strict():

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

Because throttled probes return low-confidence unknown for real addresses, treat this exactly like strict() — see the warning above. It can be combined with strict().

Custom message

(new Deliverable)->message('Please use a real, reachable email address.');

// or in strict mode
(new Deliverable)->strict()->message('That email cannot receive mail.');

Local development

This package consumes the core SDK from a sibling directory via a Composer path repository:

your-workspace/
├── bounceshift-php/       # bounceshift/bounceshift-php (core)
└── bounceshift-laravel/   # this package

composer install
composer test

Testing

composer test

Tests run against orchestra/testbench with a stubbed client — no network access is required.

License

MIT. See LICENSE.