romanzipp/laravel-mailcheck

A Laravel Wrapper for the MailCheck.ai disposable email API

2.0.2 2023-09-25 16:59 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^6.3|^7.0
• illuminate/support: ^5.5|^6.0|^7.0|^8.0|^9.0|^10.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• mockery/mockery: ^1.3.2
• orchestra/testbench: >=3.8
• phpstan/phpstan: ^0.12.99|^1.0
• phpunit/phpunit: ^8.0|^9.0
• romanzipp/php-cs-fixer-config: ^3.0

MIT

• romanzipp

README

A Laravel Wrapper for the MailCheck.ai disposable email API made by @tompec.

✨ Migrating from Validator.Pizza

This package was previously called "Validator.Pizza". See the following guide if you want to migrate your previous installation.

Migration Guide

Package name

composer remove romanzipp/laravel-validator-pizza    
composer require romanzipp/laravel-mailcheck

Config file

Update the configuration file name.

- config/mailcheck.php
+ config/mailcheck.php

Code references

- romanzipp\ValidatorPizza\
+ romanzipp\MailCheck\

Rule

- 'email' => 'required|email|validator_pizza',
+ 'email' => 'required|email|disposable', 

Table name

The default new table name will be mailcheck_checks. If you want to keep the previous validator_pizza table name change the entry in your config file.

- validator_pizza
+ mailcheck_checks

Features

• Query the MailCheck.ai API for disposable Emails & Domains
• Cache responses
• Store requested domains in database

Installation

composer require romanzipp/laravel-mailcheck

Configuration

Copy configuration to your project:

php artisan vendor:publish --provider="romanzipp\MailCheck\Providers\MailCheckProvider"

Run the migration:

php artisan migrate

Usage

Controller Validation

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class HomeController extends Controller
{
    public function handleEmail(Request $request)
    {
        $request->validate([
            'email' => 'required|email|disposable',
        ]);

        // ...
    }
}

Standalone

$checker = new \romanzipp\MailCheck\Checker;

// Validate domain
$validDomain = $checker->allowedDomain('ich.wtf');

// Validate mail address (uses domain check endpoint internally)
$validEmail = $checker->allowedEmail('[e-mail]');

Advanced Usage

You can make your disposable checks more hard or loose by configuring the edge case behavior. There are 3 possible outcomes to set:

• romanzipp\MailCheck\Enums\ApiIssue::ALLOW - allow the domain/mail
• romanzipp\MailCheck\Enums\ApiIssue::DENY - deny the chekechecked domain/mail
• romanzipp\MailCheck\Enums\ApiIssue::EXCEPTION - throw a DisposableMailException

Rate Limit exceeded

return [
    // ... 
    'decision_rate_limit' => \romanzipp\MailCheck\Enums\ApiIssue::EXCEPTION,
];

No MX DNS records present

There is no MX DNS entry present on the checked domain which means they can not receive any messages.

return [
    // ... 
    'decision_no_mx' => \romanzipp\MailCheck\Enums\ApiIssue::EXCEPTION,
];

Invalid request

return [
    // ... 
    'decision_invalid' => \romanzipp\MailCheck\Enums\ApiIssue::EXCEPTION,
];