Search by

billionverify / billionverify-php

ikbearbillionverifier

Official BillionVerify PHP SDK for email verification

Package info

github.com/BillionVerify/billionverify-php

Homepage

pkg:composer/billionverify/billionverify-php

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.1.0 2026-11-17 07:24 UTC

This package is auto-updated.

Last update: 2026-11-17 07:39:06 UTC


README

Official BillionVerify PHP SDK for email verification.

Documentation: https://billionverify.com/docs

Requirements

  • PHP 8.1 or higher
  • Composer

Installation

composer require billionverify/billionverify-php

Quick Start

<?php

require 'vendor/autoload.php';

use BillionVerify\Client;

$client = new Client('your-api-key');

// Every method returns the decoded response of the API: the result is under `data`.
// Verify a single email
$result = $client->verify('user@example.com');
echo $result['data']['status']; // 'valid', 'invalid', 'unknown', 'catchall', 'risky', 'disposable', 'role'

Configuration

$client = new Client(
    apiKey: 'your-api-key',        // Required
    baseUrl: 'https://api.billionverify.com/v1',  // Optional ("/v1" is added when missing)
    timeout: 30,                    // Optional: Request timeout in seconds (default: 30)
    retries: 3                      // Optional: Total attempts for 429/500/502/503 (default: 3)
);

Single Email Verification

// Switches you leave out (null) are not sent, so the server default applies.
$result = $client->verify(
    email: 'user@example.com',
    checkSmtp: true,                  // Optional: force SMTP checking on or off
    forceRefresh: false,              // Optional: skip every cache (a credit is always used)
    includeDomainReputation: true     // Optional: also fetch the MX IP reputation for cached results
);

echo $result['data']['email'];           // 'user@example.com'
echo $result['data']['status'];          // 'valid'
echo $result['data']['score'];           // 0.95
echo $result['data']['is_deliverable'];  // true
echo $result['data']['is_disposable'];   // false

Batch Email Verification

Verify up to 50 emails in a single synchronous request.

$results = $client->verifyBatch(
    emails: ['user1@example.com', 'user2@example.com', 'user3@example.com'],
    checkSmtp: null,                  // Optional, like verify(); forceRefresh and includeDomainReputation too
);

echo $results['data']['total_emails'];  // 3
echo $results['data']['valid_emails'];  // 2
echo $results['data']['credits_used'];  // 2

// Also in `data`: retryable_emails and deferred_emails (re-submit them later, with forceRefresh: true),
// retry_after_seconds, and deliverability_buckets with strict_deliverable, usable_with_catchall,
// not_deliverable, unknown, anti_verified and transient_failure.
echo $results['data']['deliverability_buckets']['not_deliverable'];

foreach ($results['data']['results'] as $item) {
    echo "{$item['email']}: {$item['status']}\n";
}

File Upload Verification

For larger lists, upload a file (CSV, XLSX or TXT) for asynchronous processing.

// Upload a file
$job = $client->uploadFile(
    filePath: '/path/to/emails.csv',
    checkSmtp: null,           // Optional: force SMTP checking on or off
    emailColumn: 'email',      // Optional: Column name (auto-detected if null)
    preserveOriginal: true     // Optional: Keep original columns in result (default: true)
);

echo $job['data']['task_id'];  // '7143874e-21c5-43c1-96f3-2b52ea41ae6a'

// Check job status (with optional long-polling)
$status = $client->getFileJobStatus(
    jobId: $job['data']['task_id'],
    timeout: 60  // Optional: Wait up to 60 seconds for completion (0-300)
);
echo $status['data']['status'];    // 'running'
echo $status['data']['progress'];  // 45

// Wait until the job has ended (completed, completed_with_warning, failed, cancelled) or is paused
$completed = $client->waitForFileJobCompletion(
    jobId: $job['data']['task_id'],
    pollInterval: 5,  // seconds
    maxWait: 600      // seconds
);

// Download results with optional filters
$results = $client->getFileJobResults(
    jobId: $job['data']['task_id'],
    valid: true,       // Include valid emails
    invalid: false,    // Exclude invalid emails
    catchall: true,    // Include catch-all emails
    role: false,       // Exclude role emails
    unknown: false,    // Exclude unknown emails
    disposable: false, // Exclude disposable emails
    risky: false       // Exclude risky emails
);
// The result file is served from a pre-signed storage URL. The client follows that redirect itself
// and does not send your API key to the storage host.

// Resume a paused job
$client->resumeJob($job['data']['task_id']);

Free Disposable Check

$client->checkDisposable('someone@mailinator.com')['data']['is_disposable'];          // POST
$client->checkDisposableViaQuery('someone@mailinator.com')['data']['is_disposable'];  // GET

Domain Search

Give a domain, get the emails published on its site, each one verified. It runs asynchronously and costs 5 credits per returned email; maxEmails (1-200) caps the bill.

$search = $client->createDomainSearch('example.com', maxEmails: 20, includeRoleBased: false, maxPages: 100);
$done = $client->waitForDomainSearch($search['data']['search_id']);
foreach ($done['data']['result']['emails'] as $found) {
    echo $found['email'], "\n";
}

// A CSV of domains (one results row per returned email)
$batch = $client->createDomainSearchBatch('/path/to/domains.csv', maxEmails: 10, columnMap: ['domain' => 'Company Website']);
$client->getDomainSearchBatch($batch['data']['batch_id'])['data']['progress']['processed'];
$client->listDomainSearchBatches(limit: 20, status: 'completed')['data']['items'];
$csv = $client->downloadDomainSearchBatchResults($batch['data']['batch_id']);  // 409 until the batch has finished

Health Check

Check API health (no authentication required).

// Static method - can be called without an API key
$health = Client::healthCheck();
echo $health['status'];  // 'ok'
echo $health['time'];    // Unix timestamp

// With custom base URL
$health = Client::healthCheck('https://api.billionverify.com');

Credits

$credits = $client->getCredits();

echo $credits['data']['credits_balance'];  // 9500
echo $credits['data']['credits_consumed']; // 500

Webhooks

// Create a webhook (secret is returned in response - store it securely!)
$webhook = $client->createWebhook(
    url: 'https://your-app.com/webhooks/billionverify',
    events: ['file.completed', 'file.failed']
);

echo $webhook['data']['id'];      // Webhook ID
echo $webhook['data']['secret'];  // Store this securely!

// List webhooks
$webhooks = $client->listWebhooks();
echo $webhooks['data']['webhooks'][0]['url'];

// Delete a webhook
$client->deleteWebhook($webhook['data']['id']);

// Verify a delivery: the signature is an HMAC-SHA256 of "<timestamp>.<raw body>" sent as
// X-Webhook-Signature: sha256=<hex>, with the time in X-Webhook-Timestamp.
$isValid = Client::verifyWebhookDelivery(
    payload: $rawBody,                                   // exactly as received
    signature: $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'],
    timestamp: $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'],
    secret: 'your-stored-webhook-secret',
    tolerance: 300                                       // seconds; older or future deliveries are refused, 0 turns the check off
);

Client::verifyWebhookSignature($payload, $signature, $secret) signs the body alone, which is not how the server signs deliveries; use verifyWebhookDelivery().

Error Handling

use BillionVerify\Client;
use BillionVerify\Exception\AuthenticationException;
use BillionVerify\Exception\RateLimitException;
use BillionVerify\Exception\ValidationException;
use BillionVerify\Exception\InsufficientCreditsException;
use BillionVerify\Exception\NotFoundException;
use BillionVerify\Exception\TimeoutException;
use BillionVerify\Exception\BillionVerifyException;

try {
    $result = $client->verify('user@example.com');
} catch (AuthenticationException $e) {
    echo "Invalid API key\n";
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->getRetryAfter()} seconds\n";
} catch (ValidationException $e) {
    echo "Invalid input: {$e->getMessage()}\n";
    echo "Details: {$e->getDetails()}\n";
} catch (InsufficientCreditsException $e) {
    echo "Not enough credits (HTTP 402)\n";
} catch (NotFoundException $e) {
    echo "Resource not found\n";
} catch (TimeoutException $e) {
    echo "Request timed out\n";
} catch (BillionVerifyException $e) {
    echo "Error [{$e->getErrorCode()}] HTTP {$e->getStatusCode()}: {$e->getMessage()}\n";
}

Responses with status 429, 500, 502 and 503 are retried (up to retries attempts in total), waiting Retry-After seconds when the server sends it and 2 ** attempt seconds otherwise.

Webhook Events

Available webhook events:

  • file.completed - File verification job completed successfully
  • file.failed - File verification job failed

Verification Status Values

  • valid - Email exists and can receive messages
  • invalid - Email doesn't exist or can't receive messages
  • unknown - Could not determine validity with certainty
  • catchall - Domain accepts all emails (catch-all server)
  • risky - Email is deliverable, but its domain has a confirmed abuse history: do not send (billed, never retryable)
  • disposable - Temporary/disposable email address
  • role - Role-based email (info@, support@, etc.)

Credits Usage

  • unknown status: 0 credits (not charged)
  • All other statuses (valid, invalid, risky, disposable, catchall, role): 1 credit each
  • The disposable check is free; a domain search costs 5 credits per returned email

Development

composer install
vendor/bin/phpunit

The tests use Guzzle's mock handler; they never call the real API.

Releasing

Packagist reads versions from git tags. Update CHANGELOG.md and the version in src/Client.php (Client::VERSION), run vendor/bin/phpunit, commit, then git tag vX.Y.Z && git push origin main vX.Y.Z. Packagist picks the tag up through its GitHub hook; to trigger it by hand, call the Packagist update-package API with your username and API token.

License

MIT