PHPackages                             bouncezero/bouncezero - 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. bouncezero/bouncezero

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

bouncezero/bouncezero
=====================

Official PHP client for the BounceZero email verification API

v0.1.0(1mo ago)00MITPHPPHP >=8.0

Since Jul 11Pushed 1mo agoCompare

[ Source](https://github.com/BounceZero/bouncezero-php)[ Packagist](https://packagist.org/packages/bouncezero/bouncezero)[ Docs](https://docs.bouncezero.io)[ RSS](/packages/bouncezero-bouncezero/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (2)Used By (0)

BounceZero — PHP
================

[](#bouncezero--php)

### Real-time & bulk email verification with a 5-stage intelligence pipeline

[](#real-time--bulk-email-verification-with-a-5-stage-intelligence-pipeline)

[![Packagist version](https://camo.githubusercontent.com/8c02c12117ad3c189fd7a0c3d4b4ec9f235d70a0380c3ea983b047debc72c412/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626f756e63657a65726f2f626f756e63657a65726f3f636f6c6f723d656334383939266c6162656c3d7061636b6167697374)](https://packagist.org/packages/bouncezero/bouncezero)[![PHP version](https://camo.githubusercontent.com/a7dc5d847860d3784e02eae4acc24090e8b085111b8fccdd72956a8ebfc187fd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f626f756e63657a65726f2f626f756e63657a65726f3f636f6c6f723d373737626234)](https://packagist.org/packages/bouncezero/bouncezero)[![License: MIT](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![Docs](https://camo.githubusercontent.com/c3c3c8eac98958f2ad2245f0b1888745f9e46e0a5b7f498372e5db680fdad45a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d646f63732e626f756e63657a65726f2e696f2d656334383939)](https://docs.bouncezero.io)[![Status](https://camo.githubusercontent.com/34a40007858db2cf75ddbaf7d0147fc43bf522bba0d16cca89d729e4289d45a5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d7374617475732e626f756e63657a65726f2e696f2d323263353565)](https://status.bouncezero.io)

[Documentation](https://docs.bouncezero.io) · [Dashboard](https://app.bouncezero.io/dashboard) · [API Status](https://status.bouncezero.io) · [Support](mailto:support@bouncezero.io)

---

The official PHP client for the [BounceZero](https://bouncezero.io) email verification API. **Single file, one requirement** (`ext-curl`), PHP 8.0+, with a small, predictable, typed surface built for production — from a signup form that validates one address in real time to a nightly job that cleans millions.

```
use BounceZero\BounceZero;

$client = new BounceZero('bz_live_...');
$result = $client->verify('someone@example.com');

echo $result['classification'], ' ', $result['score'];   // → verified 98
```

Why BounceZero
--------------

[](#why-bouncezero)

Every address is scored across **40+ signals** through a five-stage pipeline — syntax, DNS/MX, SMTP mailbox probing, disposable & role detection, and a Bayesian + ML confidence model — so you catch invalid, risky, and low-value addresses *before* they cost you deliverability.

- ⚡ **Real-time** single verification in ~500 ms–2 s, or **async bulk** for large lists
- 🎯 **Six clear verdicts** (`verified` / `invalid` / `catch_all` / `disposable` / `risky` / `unknown`) plus threat flags
- 🔁 **Idempotent bulk submits** — a network retry can never double-charge you
- 🧪 **Sandbox keys** to build & test without spending credits
- 🔒 **Signed webhooks** with a one-line verifier
- 📦 **PSR-friendly**, typed exceptions, automatic retries with backoff

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

[](#installation)

```
composer require bouncezero/bouncezero
```

Requires PHP 8.0+ and the cURL extension.

Authentication
--------------

[](#authentication)

Grab your API key from the [dashboard](https://app.bouncezero.io/dashboard) and pass it to the client. Keep live keys server-side — never ship them in client code.

```
require 'vendor/autoload.php';
use BounceZero\BounceZero;

$client = new BounceZero('bz_live_...');
```

Quick start
-----------

[](#quick-start)

```
// 1 — Verify a single address
$result = $client->verify('jane@example.com');
if ($result['classification'] === 'verified') {
    addToMailingList($result['email']);
}

// 2 — Batch up to 100 synchronously
$report = $client->verifyBatch(['a@example.com', 'b@example.com']);
print_r($report['summary']);            // ['verified' => 1, 'invalid' => 1, ...]

// 3 — Async bulk for large lists (idempotency-safe)
$job   = $client->verifyBulk($emails, 'import-2026-07-11');
$final = $client->waitForBulk($job['job_id']);
$csv   = $client->bulkDownload($job['job_id']);
```

Verification result
-------------------

[](#verification-result)

`verify()` returns an associative array with the full signal breakdown. The fields you'll use most:

FieldTypeDescription`email``string`The address that was checked`classification``string`One of the six verdicts below`score``int`Confidence 0–100`is_deliverable``bool|null``true`/`false`, or `null` when inconclusive`risk_level``string``low` · `medium` · `high``recommendation``string`Human-readable guidance### Classifications

[](#classifications)

VerdictMeaningSafe to send?`verified`Mailbox exists and accepts mail✅`invalid`Mailbox does not exist — will hard bounce❌`catch_all`Domain accepts everything; mailbox unconfirmable⚠️`disposable`Temporary/throwaway provider⚠️`risky`Concrete negative signals (full mailbox, poor reputation…)⚠️`unknown`Mail server blocked/greylisted the probe — retry later⏳Two rare threat verdicts — `complainer` and `spamtrap` — may also appear; remove those addresses immediately (details in `threat_type`).

API reference
-------------

[](#api-reference)

MethodDescription`verify(string $email, string $depth = 'standard')`Verify one address. `depth`: `standard` · `deep` · `ultra``verifyBatch(array $emails)`Verify up to 100 addresses synchronously`verifyBulk(array $emails, ?string $idempotencyKey = null)`Submit an async bulk job`bulkStatus(string $jobId)`Poll job progress`bulkResults(string $jobId, int $limit = 1000, int $offset = 0)`Paginated results`bulkDownload(string $jobId)`Download completed results as a CSV string`waitForBulk(string $jobId, float $pollInterval = 5.0, float $timeout = 3600.0)`Block until a job finishes`domain(string $domain)`Domain-level intelligence (MX, provider, catch-all…)`analyzeList(array $emails)`Free list-quality analysis — no verification, no credits`BounceZero::verifyWebhookSignature($body, $header, $secret)`Validate a webhook signatureBulk verification
-----------------

[](#bulk-verification)

Bulk jobs run asynchronously. Submit, then either block or poll:

```
$job = $client->verifyBulk($emails, 'crm-sync-42');

// Option A — block until done
$final = $client->waitForBulk($job['job_id'], pollInterval: 10.0);

// Option B — poll yourself
$status = $client->bulkStatus($job['job_id']);
echo $status['completed'], ' / ', $status['total'];

// Fetch results (paginated) or download the full CSV
$page = $client->bulkResults($job['job_id'], limit: 1000, offset: 0);
$csv  = $client->bulkDownload($job['job_id']);
```

**Idempotency** — pass an `$idempotencyKey` (any unique string). Replaying the same key returns the *original* job instead of creating and charging for a duplicate, so retries after a timeout are always safe.

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

[](#error-handling)

Every failure throws a subclass of `BounceZero\BounceZeroException`, each carrying `->statusCode` and `->payload`:

```
use BounceZero\{BounceZeroException, AuthenticationException,
    InsufficientCreditsException, RateLimitException};

try {
    $result = $client->verify('someone@example.com');
} catch (InsufficientCreditsException $e) {
    topUpCredits();
} catch (RateLimitException $e) {
    sleep((int) ($e->retryAfter ?? 60));
} catch (AuthenticationException $e) {
    alert('Check your API key');
} catch (BounceZeroException $e) {
    error_log("BounceZero {$e->statusCode}: {$e->getMessage()}");
}
```

ExceptionHTTPWhen`AuthenticationException`401 / 403Missing, invalid, disabled, or IP-restricted key`InsufficientCreditsException`402Not enough credits`NotFoundException`404Unknown job or resource`RateLimitException`429Plan rate limit exceeded (see `->retryAfter`)`BounceZeroException`otherAny other API/transport errorRequests automatically retry on `429` and `5xx` with exponential backoff (honoring `Retry-After`); tune with the `$maxRetries` constructor argument.

Rate limits
-----------

[](#rate-limits)

Limits are per API key, per minute, by plan. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.

PlanRequests / minFree30Starter · Growth100Professional · Business · Scale300Ultimate · Enterprise1000Sandbox / testing
-----------------

[](#sandbox--testing)

Create a **sandbox key** (`bz_test_` prefix) in the dashboard. It returns deterministic mock results, never spends credits, and never performs a real probe — the local part of the address picks the verdict:

```
$sandbox = new BounceZero('bz_test_...');
$sandbox->verify('verified@example.com')['classification'];   // → "verified"
$sandbox->verify('risky@example.com')['classification'];      // → "risky"
```

Supported on `verify()`. See the [sandbox docs](https://docs.bouncezero.io#sandbox).

Webhooks
--------

[](#webhooks)

BounceZero signs every webhook with `X-BounceZero-Signature` (HMAC-SHA256). Always verify against the **raw** request body before parsing:

```
use BounceZero\BounceZero;

$raw = file_get_contents('php://input');
$ok  = BounceZero::verifyWebhookSignature(
    $raw,
    $_SERVER['HTTP_X_BOUNCEZERO_SIGNATURE'] ?? '',
    $signingSecret,            // from Dashboard → Webhooks
);
if (!$ok) {
    http_response_code(400);
    exit;
}
$event = json_decode($raw, true);
// ...
```

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

[](#configuration)

```
$client = new BounceZero(
    apiKey: 'bz_live_...',
    baseUrl: 'https://app.bouncezero.io',  // override for a dedicated region
    timeout: 60,                           // seconds
    maxRetries: 2,                         // retries on 429 / 5xx
);
```

Support
-------

[](#support)

- 📖 Documentation —
- 📊 API status —
- ✉️

License
-------

[](#license)

[MIT](LICENSE) © BounceZero Ltd

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity28

Early-stage or recently created project

 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

50d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e0c3f8860071f3d2ee8deb682487ef53c7d430de45ce2ab9c876f1d9639c6409?d=identicon)[BounceZero](/maintainers/BounceZero)

---

Top Contributors

[![BounceZero](https://avatars.githubusercontent.com/u/302599019?v=4)](https://github.com/BounceZero "BounceZero (2 commits)")

---

Tags

validationemailverificationdeliverabilitybouncezero

### Embed Badge

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

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

###  Alternatives

[egulias/email-validator

A library for validating emails against several RFCs

11.7k767.4M530](/packages/egulias-email-validator)[kickbox/kickbox

Official kickbox API library client for PHP

591.1M4](/packages/kickbox-kickbox)[neverbounce/neverbounce-php

This package provides convenient methods to integrate the NeverBounce API into your project.

241.3M4](/packages/neverbounce-neverbounce-php)[erag/laravel-disposable-email

A Laravel package to detect and block disposable email addresses.

269221.0k1](/packages/erag-laravel-disposable-email)[dominicsayers/isemail

Checks an email address against the following RFCs: 3696, 1123, 4291, 5321, 5322

309150.4k3](/packages/dominicsayers-isemail)[arubacao/tld-checker

Top Level Domain (TLD) validation library for PHP

741.8M4](/packages/arubacao-tld-checker)

PHPackages © 2026

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