PHPackages                             apiddress/sdk - 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. apiddress/sdk

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

apiddress/sdk
=============

Official PHP SDK for the APIddress email validation API

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

Since Jun 13Pushed 1mo agoCompare

[ Source](https://github.com/Yayabtw/sdk-php)[ Packagist](https://packagist.org/packages/apiddress/sdk)[ RSS](/packages/apiddress-sdk/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

apiddress/sdk
=============

[](#apiddresssdk)

Official PHP SDK for the [APIddress](https://api.apiddress.com) 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
-------

[](#install)

```
composer require apiddress/sdk
```

Quickstart
----------

[](#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
-------------

[](#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
-----

[](#usage)

### Validate one email

[](#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

[](#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-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

[](#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
--------------

[](#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" => ...]
}
```

`status``code`400`invalid_request`401`unauthorized`404`not_found`429`quota_exceeded`500`internal_error`0`timeout` (request or `waitForBatch` timeout)Development
-----------

[](#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
-------

[](#license)

MIT

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

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

45d ago

### Community

Maintainers

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

---

Top Contributors

[![Yayabtw](https://avatars.githubusercontent.com/u/78480186?v=4)](https://github.com/Yayabtw "Yayabtw (1 commits)")

---

Tags

validationemailemail-verificationapiddress

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[egulias/email-validator

A library for validating emails against several RFCs

11.6k734.8M453](/packages/egulias-email-validator)[stymiee/email-validator

A robust PHP 7.4+ email validation library that extends beyond basic validation with MX record checks, disposable email detection, and free email provider validation. Features include strict typing, custom validator support, internationalization (i18n), and an extensible architecture. Perfect for applications requiring thorough email verification with customizable validation rules.

33487.3k1](/packages/stymiee-email-validator)[daveearley/daves-email-validation-tool

An easy to use, accurate-ish & extensible email validation library for PHP 7+

284345.7k2](/packages/daveearley-daves-email-validation-tool)[dominicsayers/isemail

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

309144.3k3](/packages/dominicsayers-isemail)[erag/laravel-disposable-email

A Laravel package to detect and block disposable email addresses.

254168.5k](/packages/erag-laravel-disposable-email)[arubacao/tld-checker

Top Level Domain (TLD) validation library for PHP

731.7M3](/packages/arubacao-tld-checker)

PHPackages © 2026

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