MailCheckr for Laravel

Laravel client for the MailCheckr API. Requires PHP 8.2+ and Laravel 10–13.

Install

composer require dotmarn/mailcheckr-php

The service provider and facade are discovered automatically. Add your server-side API key to .env:

MAILCHECKR_API_KEY=mc_live_your_api_key
MAILCHECKR_WEBHOOK_SECRET=your_webhook_signing_secret

Optional settings: MAILCHECKR_BASE_URL, MAILCHECKR_TIMEOUT (seconds, default 30), and MAILCHECKR_WEBHOOK_TOLERANCE (seconds, default 300). Publish the configuration with php artisan vendor:publish --tag=mailcheckr-config.

Verify an address

Using the facade:

use Dotmarn\MailCheckr\Facades\MailCheckr;

$verification = MailCheckr::verify(
    'person@example.com',
    'verify-user-123' // persist and reuse this key for retries of the same email
);

if ($verification->isPending()) {
    $verification = MailCheckr::find($verification->id()); // Poll later, not in a tight loop.
}

if ($verification->isDeliverable()) {
    // The verification completed and MailCheckr marked it deliverable.
} elseif ($verification->isUnknown()) {
    // The verification completed without a conclusive delivery result.
}

Using the client class directly:

use Dotmarn\MailCheckr\MailCheckrClient;

$client = new MailCheckrClient();
$verification = $client->verify('person@example.com', 'verify-user-123');

if ($verification->isPending()) {
    $verification = $client->find($verification->id()); // Poll later, not in a tight loop.
}

if ($verification->isDeliverable()) {
    // The verification completed and MailCheckr marked it deliverable.
}

verify() and find() return a VerificationResult for HTTP 200 and 202. Pending states include queued, processing, and retry_scheduled; poll the ID or handle a webhook. Do not treat a pending or unknown result as deliverable.

VerificationResult also provides isUndeliverable(), isRisky(), isCompleted(), and isFailed(). The four status helpers return true only when the state is completed; a queued result is never treated as deliverable. Use id(), state(), status(), or toArray() to inspect the response. The facade and MailCheckrClient expose the same methods.

API errors throw Dotmarn\MailCheckr\Exceptions\MailCheckrException, with status and response properties. Network errors are raised by Laravel's HTTP client.

Verify webhook deliveries

Configure an HTTPS endpoint in the MailCheckr dashboard. Put the route below in routes/api.php so Laravel's web CSRF middleware does not reject MailCheckr's POST requests. In Laravel 11–13, add api: __DIR__.'/../routes/api.php' to the existing withRouting(...) call in bootstrap/app.php if API routing is not already registered. With Laravel's default API prefix, set the dashboard URL to https://your-app.example/api/webhooks/mailcheckr.

Verify the raw request body before processing verification.completed or bulk_verification.completed:

use Dotmarn\MailCheckr\WebhookVerifier;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/mailcheckr', function (Request $request, WebhookVerifier $verifier) {
    abort_unless($verifier->verify($request), 401);

    $event = $request->json()->all();
    // Deduplicate by $event['id'] in persistent storage before applying effects.

    return response()->noContent();
});

The verifier checks the X-MailCheckr-Signature HMAC against X-MailCheckr-Timestamp and the exact body, and rejects timestamps outside the configured tolerance. Store processed event IDs because valid deliveries may be retried.

Contributing

Please feel free to fork this package and contribute by submitting a pull request to enhance the functionalities.

How can I thank you?

Why not star the github repo? I'd love the attention! Why not share the link for this repository on Twitter.

Don't forget to follow me on twitter!

License

The MIT License (MIT). Please see License File for more information.