README

🗑 Disposable email detection

PHP package that detects disposable (temporary/throwaway/fake) email addresses. It is framework-agnostic and has no dependencies, but includes support for Laravel. It validates email addresses to ensure they are genuine, which is useful for managing account sign-ups and assessing the number of legitimate email addresses in your system. This tool also helps to avoid communication errors and blocks spam addresses.
The lookup is superfast because disposable email domains are stored locally as a native php hash set.

The list of disposable email domains is regularly updated automatically from trusted external sources.

Supported PHP versions: v7.2 - v8.3

Installation and Usage examples

Note

Read below for Laravel specific instructions.

Require this package with composer using the following command:

composer require beeyev/disposable-email-filter-php

Basic usage

Simple check if the email address is disposable:

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

use Beeyev\DisposableEmailFilter\DisposableEmailFilter;

$disposableEmailFilter = new DisposableEmailFilter();

// Check if email address is disposable
$disposableEmailFilter->isDisposableEmailAddress('ostap@gmail.com'); // false
$disposableEmailFilter->isDisposableEmailAddress('john@tempmailer.com'); // true

Adding custom disposable(blacklisted) and whitelisted domains:

Note: Whitelisted domains have higher priority than blacklisted domains.

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

use Beeyev\DisposableEmailFilter\DisposableEmailFilter;

$disposableEmailFilter = new DisposableEmailFilter();

// Add multiple custom domains to blacklist
$disposableEmailFilter->blacklistedDomains()->addMultiple(['mailinator.com', '10minute-mail.org']);

// Add one domain to whitelist
$disposableEmailFilter->whitelistedDomains()->add('tempmailer.com');

$disposableEmailFilter->isDisposableEmailAddress('john@tempmailer.com'); // false (because it's whitelisted now)
$disposableEmailFilter->isDisposableEmailAddress('john@mailinator.com'); // true
$disposableEmailFilter->isDisposableEmailAddress('john@10minute-mail.org'); // true
$disposableEmailFilter->isDisposableEmailAddress('john@gmail.com'); // false

It is also possible to add blacklisted and whitelisted domains using constructor dependency:

use Beeyev\DisposableEmailFilter\CustomEmailDomainFilter\CustomEmailDomainFilter;
use Beeyev\DisposableEmailFilter\DisposableEmailFilter;

$blacklistedDomains = new CustomEmailDomainFilter(['blacklisted1.com', 'blacklisted2.com', 'blacklisted3.com']);
$whitelistedDomains = new CustomEmailDomainFilter(['abc2.com', 'whitelisted1.com']);
$disposableEmailFilter = new DisposableEmailFilter($blacklistedDomains, $whitelistedDomains);

$disposableEmailFilter->isDisposableEmailAddress('test@whitelisted1.com'); // false - whitelisted

Note: You can develop your own filtration logic by creating a custom class that implements the CustomEmailDomainFilterInterface

Handling exceptions:

If you try to pass empty string or string with invalid email format, an exception will be thrown.

use Beeyev\DisposableEmailFilter\DisposableEmailFilter;
use Beeyev\DisposableEmailFilter\Exceptions\InvalidEmailAddressException;

$disposableEmailFilter = new DisposableEmailFilter();

try {
    $disposableEmailFilter->isDisposableEmailAddress('john:gmail.com'); // Exception will be thrown because of invalid email format
} catch (InvalidEmailAddressException $e) {
    echo $e->getMessage();
}

If you expect that email address might be invalid and don't want to wrap the code into try/catch,
you can use isDisposableEmailAddressSafe method to check if email address is correctly formatted before checking if it's disposable:

$disposableEmailFilter = new DisposableEmailFilter();

$emailAddress = 'john:gmail.com';

if ($disposableEmailFilter->isEmailAddressValid($emailAddress)) {
    $disposableEmailFilter->isDisposableEmailAddress($emailAddress);
}

Laravel specific usage

This package includes a service provider and form validation rule for Laravel.

Install the package (Laravel)

composer require beeyev/disposable-email-filter-php

The package will be automatically registered using Laravel auto-discovery mechanism.
But if you need to do it manually, you can add the following line to the providers array in the config/app.php file:

Beeyev\DisposableEmailFilter\Adapters\Laravel\DisposableEmailFilterServiceProvider::class,

Form validation (Laravel)

Use validation rule not_disposable_email or object new NotDisposableEmail(), to check that specific field does not contain a disposable email address.

Note

❗ Place it after the email validator to ensure that only valid emails are processed.

Example:

// Using validation rule name:
'email_field' => 'required|email|not_disposable_email',

// Or using a validation rule object:
'email_field' => ['email', new NotDisposableEmail()],

Using facades (Laravel)

You can use the DisposableEmail facade to access the DisposableEmailFilter instance:

use Beeyev\DisposableEmailFilter\Adapters\Laravel\Facades\DisposableEmail;

DisposableEmail::isEmailAddressValid('foo@fakemail.com');

Config file and translations (Laravel)

Optionally, you can publish the config file and translations to customize the package behavior:

php artisan vendor:publish --tag=disposable-email-filter

This command will create a disposable-email-filter.php config file in the config directory and translation files in the lang/vendor/disposable-email-filter directory.

Updating

Since the list of disposable email domains is regularly updated, it is important to keep the package up to date.
A new PATCH version of the package is released whenever the list is updated.
These updates are safe and non-breaking, allowing you to update the package via this composer command:

composer update beeyev/disposable-email-filter-php

You can run this command every time in CI/CD pipelines before the project is deployed.

Contribution

Feel free to contribute to this project if you want to add new features, improve existing ones, or fix bugs.
To add new disposable domains, you can update the blacklist.txt file and create a pull request.
Alternatively, you can open an issue with the domains you want to be added to the blacklist or whitelist.

External Sources:

Local blacklist and whitelist are stored in the blacklist.txt and whitelist.txt files.

Issues

Bug reports and feature requests can be submitted on the Github Issue Tracker.

License

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

If you love this project, please consider giving me a ⭐

beeyev / disposable-email-filter-php

Maintainers

Details