Download the PHP package bounceshift/bounceshift-php without Composer

BounceShift PHP SDK

Framework-agnostic PHP client for the BounceShift 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: https://bounceshift.com/docs/api

Installation

The SDK relies on PSR-18 HTTP Client Discovery. Guzzle is included as a default implementation; any PSR-18 client works.

Quickstart

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

Configuration

The result object

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

ValidationResult::isSafeToSend() returns true only when the status is valid or catch_all.

ValidationResult::isSendable() surfaces the API's actionable recommendation instead: it returns true only when recommendation is deliverable or send_with_caution. An absent, null, or unrecognized recommendation is treated as not sendable (and never throws).

Typo suggestions

didYouMean carries the corrected address when the domain is within a character or two of a major provider, and null otherwise. hasSuggestion() is the convenience check.

Two things to know:

• It is advisory. The API validates the address you sent, never the suggestion, and the verdict is unaffected. Put the correction in front of the person who typed it rather than substituting it — the mailbox at the misspelled domain may genuinely exist, and swapping it silently means mailing an address you were never given.
• It is populated on any status, including valid and disposable. That is deliberate: misspellings like gmil.com and hotmial.com are registered and accept mail, so they never bounce and never appear in a bounce report. The suggestion is the only signal you get for them.

Recommendations

BounceShift\Recommendation is a string-backed enum:

deliverable, send_with_caution, risky, undeliverable, unknown.

Statuses

BounceShift\ValidationStatus is a string-backed enum:

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

Error handling

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

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

Fail open — never block your users

On a hot path such as validate-on-signup, a validation problem should never block the user. If your account runs out of credits, or the API is down, timing out, or unreachable, you almost always want to let the address through rather than crash the signup. Use validateSafe() — it never throws:

A degraded result has status unknown, creditsUsed = 0, and isDegraded() === true, so you can always tell "we couldn't check" apart from a genuine unknown verdict. Reach for validate() (which throws the typed exceptions above) only when you want to handle each failure yourself.

The timeout / connect_timeout options bound how long a stalled API can hold your request thread before validateSafe() returns a degraded result.

Testing

License

MIT. See LICENSE.