README

Official PHP SDK for the MailSentry email validation API.

Requirements

PHP 8.1 or higher
Guzzle HTTP 7.x

Installation

composer require mailsentry/mailsentry-php

Quick Start

<?php

require_once 'vendor/autoload.php';

use MailSentry\MailSentry;
use MailSentry\MailSentryException;

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

try {
    $result = $client->verify('user@example.com');

    echo $result['email'];    // "user@example.com"
    echo $result['score'];    // 0-100
    echo $result['verdict'];  // "valid", "caution", "risky", or "invalid"
} catch (MailSentryException $e) {
    echo 'Error: ' . $e->getMessage();
    echo 'Status: ' . $e->getStatusCode();
}

Usage

Initialize the Client

use MailSentry\MailSentry;

// Default (connects to https://mailsentry.dev)
$client = new MailSentry('your-api-key');

// Custom base URL and timeout
$client = new MailSentry(
    apiKey: 'your-api-key',
    baseUrl: 'https://mailsentry.dev',
    timeout: 60.0,
);

Verify a Single Email

$result = $client->verify('user@example.com');

// Full response structure:
// [
//     'email' => 'user@example.com',
//     'score' => 92,
//     'verdict' => 'valid',
//     'recommendation' => 'Safe to send',
//     'verification_level' => 'confirmed',
//     'warning' => null,
//     'checks' => [
//         'syntax' => ['valid' => true],
//         'mx_records' => ['valid' => true, 'records' => [...]],
//         'disposable' => ['is_disposable' => false],
//         'role_based' => ['is_role_based' => false],
//         'free_provider' => ['is_free' => true, 'name' => 'Gmail'],
//         'typo' => ['has_typo' => false, 'suggestion' => null],
//         'smtp' => ['valid' => true, 'catch_all' => false],
//         'gibberish' => ['is_gibberish' => false, 'score' => 0.1],
//         'spam_trap' => ['is_potential_trap' => false, 'type' => null],
//         'domain_age' => ['domain_created' => '1995-08-13', 'age_days' => 11000],
//         'abuse' => ['is_toxic' => false, 'type' => null],
//     ],
//     'response_time_ms' => 42,
// ]

Bulk Verify Emails

// Submit a batch of emails for validation
$job = $client->bulkVerify([
    'alice@example.com',
    'bob@test.org',
    'carol@company.io',
]);

echo $job['id'];     // Bulk job ID
echo $job['status']; // "processing" or "completed"
echo $job['total'];  // Number of emails submitted

// With an optional filename label
$job = $client->bulkVerify($emails, 'march-campaign.csv');

Get Bulk Job Details

$job = $client->getBulkJob('job-id-here');

echo $job['status'];       // "processing" or "completed"
echo $job['total_emails'];
echo $job['processed'];

foreach ($job['results'] as $result) {
    echo $result['email'] . ': ' . $result['verdict'] . "\n";
}

List Bulk Jobs

$jobs = $client->listBulkJobs();

foreach ($jobs as $job) {
    echo $job['id'] . ' — ' . $job['status'] . "\n";
}

Error Handling

All API errors throw MailSentryException, which includes the HTTP status code.

use MailSentry\MailSentryException;

try {
    $result = $client->verify('test@example.com');
} catch (MailSentryException $e) {
    echo $e->getMessage();    // Error message from the API
    echo $e->getStatusCode(); // HTTP status code (e.g. 401, 429)
}

API Key

Get your free API key at mailsentry.dev/signup. The free plan includes 1,000 validations per month.

Documentation

Full API docs: mailsentry.dev/docs

License

MIT

mailsentry / mailsentry-php

Maintainers

Package info

Statistics

Security