README

A beginner-friendly PHP SDK for the Listclean API. The SDK wraps the official endpoints so you can verify emails, manage uploads, and monitor account details with simple PHP method calls.

Requirements

PHP 7.2 or higher
cURL extension enabled (default for most PHP installations)
A Listclean API key (available from your Listclean dashboard)

Installation

Use Composer to add the SDK to your project:

composer require listclean/listclean-php

If you are installing from source, make sure to include the Composer autoloader:

require __DIR__ . '/vendor/autoload.php';

Quick start

<?php
require __DIR__ . '/vendor/autoload.php';

use Listclean\Listclean;

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

// Verify a single email address
$result = $client->verifyEmail('user@example.com');

if ($result['success'] ?? false) {
    $status = $result['data'][0]['status'] ?? 'unknown';
    echo "Status: {$status}" . PHP_EOL;
}

API coverage

The SDK currently supports the following endpoints from the OpenAPI specification:

Feature	Method	Endpoint
Verify a single email	`verifyEmail(string $email)`	`GET /verify/email/{email}`
Verify a batch of emails	`verifyEmailBatch(array $emails)`	`POST /verify/email/batch`
Fetch verification logs	`getVerificationLogs()`	`GET /verify/email/logs`
List uploads	`listUploads()`	`GET /uploads/`
Start an upload	`startUpload(array $payload)`	`POST /uploads/`
Upload a chunk	`uploadChunk(int $uploadId, array $payload)`	`POST /uploads/{upload_id}`
Get upload status	`getUploadStatus(int $uploadId)`	`GET /uploads/{upload_id}`
List all lists	`listLists()`	`GET /lists/`
Get a list	`getList(int $listId)`	`GET /lists/{list_id}`
Delete a list	`deleteList(int $listId)`	`DELETE /lists/{list_id}`
Download list as CSV	`downloadListCsv(int $listId, string $type, ?string $tokenOverride = null)`	`GET /downloads/{list_id}/{type}/`
Download list as JSON	`downloadListJson(int $listId, string $type, ?string $tokenOverride = null)`	`GET /downloads/json/{list_id}/{type}/`
Get account profile	`getProfile()`	`GET /account/profile/`
Update account profile	`updateProfile(array $payload)`	`POST /account/profile/`
Check credits	`getCredits()`	`GET /credits`

Handling errors

All methods can throw a Listclean\Exceptions\ApiException if something goes wrong (for example, invalid credentials or a malformed request). Catch this exception to inspect the HTTP status code and response body:

use Listclean\Exceptions\ApiException;

try {
    $client->verifyEmail('user@example.com');
} catch (ApiException $exception) {
    echo 'Status code: ' . $exception->getStatusCode();
    print_r($exception->getResponseBody());
}

Examples

The examples/ directory contains small scripts that show how to:

Verify a single email (examples/verify_single.php)
Verify a batch of emails (examples/verify_batch.php)
Start an upload and track its progress (examples/upload_list.php)

Run an example by setting your API key and executing it with PHP:

API_KEY="your-api-key" php examples/verify_single.php

Each example reads the API key from the API_KEY environment variable to keep secrets out of source control.

Contributing

Fork the repository and create a feature branch.
Run composer dump-autoload after adding new classes.
Submit a pull request with a clear description of the changes.

Feel free to open issues for questions or feature requests!

listclean / listclean-php

Maintainers

Details