README

Official PHP SDK for the APIddress email validation API.

• Zero Composer runtime dependencies (stdlib curl extension only)
• PHP 8.1+, fully typed with readonly properties, PSR-4 autoloading
• Automatic retry with backoff on 429 and 5xx (batch creation is never retried)

Install

composer require apiddress/sdk

Quickstart

use Apiddress\Client;

$client = new Client($_ENV['APIDDRESS_API_KEY']);

$result = $client->validateEmail('ada@stripe.com');
echo $result->status; // "valid"
echo $result->score;  // 0.98

Configuration

$client = new Client(
    apiKey:     'YOUR_API_KEY',
    baseUrl:    'https://api.apiddress.com', // default
    timeout:    10,                          // per-request timeout (seconds), default 10
    maxRetries: 2,                           // retries on 429/5xx, default 2
);

Usage

Validate one email

$result = $client->validateEmail(
    'john@company.com',
    checkSmtp:      false, // default
    allowRoleBased: true,  // server default
);
// $result->status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
// $result->suggestion: "john@gmail.com" for typo-like addresses, else null
// $result->checks: ValidationChecks { syntax, domain_exists, mx, smtp, disposable, ... }

A malformed value (e.g. "not-an-email") is a verdict, not an error: you get status === "invalid" with reason === "invalid_syntax".

Validate up to 100 emails synchronously

$response = $client->validateEmails(['a@example.com', 'b@example.com']);
echo $response->count;
foreach ($response->results as $r) {
    echo $r->email . ' ' . $r->status . PHP_EOL;
}

Batch jobs (up to 5000 emails)

$batch = $client->createBatch(
    $emails,
    callbackUrl: 'https://yourapp.com/webhooks/apiddress', // optional
);

$done = $client->waitForBatch(
    $batch->batch_id,
    pollInterval: 1.0,  // default
    timeout:      60.0, // default
);
echo $done->status . ' ' . count($done->results);

// Or poll yourself:
$status = $client->getBatch($batch->batch_id);

waitForBatch returns the terminal state ("completed" or "failed") — check status before using results.

Account

$profile = $client->me();           // plan, limits, usage
$usage   = $client->usage();        // current month
$may     = $client->usage('2026-05'); // specific month
$health  = $client->health();       // no auth required

Error handling

Every failed request throws an APIddressError:

use Apiddress\APIddressError;
use Apiddress\Client;

try {
    $client->validateEmail('john@company.com');
} catch (APIddressError $err) {
    echo $err->status;  // 429
    echo $err->code;    // "quota_exceeded"
    echo $err->getMessage(); // "Monthly request limit exceeded."
    var_dump($err->details); // ["requests_used" => ..., "requests_limit" => ...]
}

Development

composer install
composer exec phpunit

# Integration tests need a live backend:
APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev \
  composer exec phpunit

License

MIT