README

A comprehensive PHP SDK for the EmailVerify.io API. This SDK provides an easy-to-use interface for all EmailVerify.io API features including email validation, email finder, and batch processing operations.

Features

Single email validation
Email finder (find an email address using a name and domain)
Batch email validation
Account balance checking
Robust error handling

Requirements

PHP 7.4 or higher
ext-json
ext-curl

Installation

Install the package via Composer:

composer require emailverifyio/emailverify

Quick Start

use EmailVerify\SDK\EmailVerify;

// Initialize with your API key
EmailVerify::Instance()->initialize('<YOUR_API_KEY>');

// Validate an email address
$result = EmailVerify::Instance()->validate('test@example.com');
echo "Status: " . $result->status . "\n";  // valid, invalid, unknown, etc.

Detailed Usage

Initialize the SDK

Always initialize the SDK with your API key before making any API calls:

use EmailVerify\SDK\EmailVerify;
use EmailVerify\SDK\EVException;

try {
    // Initialize with your API key
    EmailVerify::Instance()->initialize('your-api-key');
} catch (EVException $e) {
    // Handle any initialization errors
    echo "Error: " . $e->getMessage() . "\n";
}

Email Validation

Validate a single email address to check its deliverability:

try {
    $result = EmailVerify::Instance()->validate('<EMAIL_ADDRESS>');
    
    echo "Email: " . $result->email . "\n";
    echo "Status: " . $result->status . "\n";
    echo "Sub-Status: " . $result->subStatus . "\n";
    
    // Determine if email is valid
    if ($result->status === 'valid') {
        echo "The email is valid and deliverable.\n";
    } else if ($result->status === 'invalid') {
        echo "The email is not deliverable.\n";
    } else {
        echo "The email validation is inconclusive.\n";
    }
} catch (EVException $e) {
    echo "Error Message: " . $e->getMessage() . "\n";
    echo "Error Code: " . $e->getErrorCode() . "\n";
    $context = $e->getErrorContext();
    echo "Error Context : " .  print_r($context, true)  . "\n";
}

Email Finder

Find an email address using a person's name and domain:

try {
    $result = EmailVerify::Instance()->findEmail('<NAME>', '<DOMAIN.COM>');
    
    if ($result->status === 'found') { // Status can found or not_found
        echo "Email found: " . $result->email . "\n";
        // Use the found email for your purposes
    } else {
        echo "No email found for this name and domain combination.\n";
    }
} catch (EVException $e) {
    echo "Error Message: " . $e->getMessage() . "\n";
    echo "Error Code: " . $e->getErrorCode() . "\n";
    $context = $e->getErrorContext();
    echo "Error Context : " .  print_r($context, true)  . "\n";
}

Check Account Balance

Check your API usage and remaining credits:

try {
    $result = EmailVerify::Instance()->checkAccountBalance();

    print_r($result);
    echo "Api Status: " . $result->apiStatus . "\n"; 
    echo "Daily Credit Limit: " . $result->dailyCreditsLimit . "\n"; 
    echo "Remaining Credits: " . $result->remainingCredits . "\n"; 
    echo "Referral Credits: " . $result->referralCredits . "\n";  //null for appsumo users
    echo "Remaining Daily Credits: " . $result->remainingDailyCredits . "\n"; //null for non-AppSumo users  
    echo "Bonus Credits: " . $result->bonusCredits . "\n"; //null for non-AppSumo users 
} catch (EVException $e) {
    echo "Account balance check error: " . $e->getMessage() . "\n";
}

Batch Email Validation

Validate multiple emails at once for better performance:

try {
    $emails = [
        'user1@example.com',
        'user2@example.com',
        'invalid@example.com'
    ];
    
    $result = EmailVerify::Instance()->validateBatch('<TITLE>', $emails); // Title and emails are required field
    
    echo "Status: " . $result->status . "\n";
    echo "Task ID: " . $result->taskId . "\n"; # IMPORTANT SAVE THIS ID TO CHECK RESULT LATER
    echo "Count Submitted: " . $result->countSubmitted . "\n";
    echo "Count Duplicate Removed: " . $result->countDuplicateRemoved . "\n";
    echo "Count Processing: " . $result->countProcessing . "\n";
    echo "Full result object:\n";
    print_r($result);

    // Store the task ID to check results later
    // You can save this to your database or file
    $taskId = $result->taskId;
} catch (EVException $e) {
    echo "Batch validation error: " . $e->getMessage() . "\n";
}

Get Batch Validation Results

Retrieve and process the results of a previously submitted batch job:

try {
    // Use the task ID from your previous batch submission
    $task_id = 2900;
    $result = EmailVerify::Instance()->getBatchResults($task_id);
    
    echo "Status: " . $result->status . "\n";
    echo "Count Check: " . $result->countChecked . "\n";
    echo "Count Total: " . $result->countTotal . "\n";
    echo "Name: " . $result->name . "\n";
    echo "TaskId: " . $result->taskId . "\n";
    echo "Progress: " . $result->progressPercentage . "\n";
    
    // Check if the batch processing is complete
    if ($result->status === 'verified') {
        echo "Batch processing complete. Results:\n";
        
        // Process each email result
        foreach ($result->results->emailBatch as $emailResult) {
            echo $emailResult['address'] . ": " . $emailResult['status'];
            if (isset($emailResult['sub_status'])) {
                echo " (" . $emailResult['sub_status'] . ")";
            }
            echo "\n";
        }
    } else {
        echo "Batch still processing. Check back later.\n";
    }
} catch (EVException $e) {
    echo "Batch results retrieval error: " . $e->getMessage() . "\n";
}

Error Handling

The SDK uses custom exception classes for different error scenarios:

use EmailVerify\SDK\EVException;
use EmailVerify\SDK\EVMissingApiKeyException;
use EmailVerify\SDK\EVMissingParameterException;

try {
    $result = EmailVerify::Instance()->validate('test@example.com');
    // Process result...
} catch (EVMissingApiKeyException $e) {
    // Handle missing API key error
    echo "Please configure your API key first.\n";
} catch (EVMissingParameterException $e) {
    // Handle missing parameter error
    echo "Missing required parameter: " . $e->getMessage() . "\n";
} catch (EVException $e) {
    // Handle general API errors
    echo "API Error: " . $e->getMessage() . "\n";
    
    // Access detailed error context if available
    if ($e->hasErrorContext()) {
        $errorContext = $e->getErrorContext();
        echo "Error details: " . json_encode($errorContext) . "\n";
    }
} catch (\Exception $e) {
    // Handle any other unexpected errors
    echo "Unexpected error: " . $e->getMessage() . "\n";
}

Development

Install development dependencies

composer install --dev

The SDK includes PHPUnit tests to ensure functionality:

# Run all tests
./vendor/bin/phpunit --bootstrap vendor/autoload.php tests/

# Run a specific test file
./vendor/bin/phpunit --bootstrap vendor/autoload.php tests/EmailVerifyTest.php

emailverifyio / emailverify

Maintainers

Details