billionverify / billionverify-php
Official BillionVerify PHP SDK for email verification
Package info
github.com/BillionVerify/billionverify-php
pkg:composer/billionverify/billionverify-php
Requires
- php: >=8.1
- guzzlehttp/guzzle: ^7.0
Requires (Dev)
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ^10.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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 successfullyfile.failed- File verification job failed
Verification Status Values
valid- Email exists and can receive messagesinvalid- Email doesn't exist or can't receive messagesunknown- Could not determine validity with certaintycatchall- 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 addressrole- Role-based email (info@, support@, etc.)
Credits Usage
unknownstatus: 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