README.md

Laravel Email Checker

Validates email addresses belong to their domain.

Report Bug · Request Feature

Table of Contents

1. About The Package
   • Built With
2. Getting Started
   • Requires
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

Flexible and simple library for checking email addresses. Usual framework validators are usually checking email correctness, but this library is implementing other kind of validation.

It can check is mail:

• registered in mail provider from forbidden country;
• registered in forbidden domain (all possible levels);
• used for spam or scam (dangerous), temporary, had suspicious behaviour, is registered on paid or public (like gmail) mail provider.

Of course, you can always propose new domains to add into listed in the "data" directory.

Key feautures:

• fast search - binary search in the pre-sorted dictionaries (in comparison with other popular libraries with linear search)
• flexible configurations - not only one strict list
• low memory usage - disctionaries are not loaded fully into memory (as in other popular libraries)
• frequent updates
• easy collaboration
• large disctionary- 60k+ of domains (not only public email providers) in the dictionary

(back to top)

Built With

This library supports several languages and frameworks.

• PHP
  • 
  • Laravel (current)
  • Symfony (planned)
  • Phalcon (planned)
• JS / TS
  • Vanilla (planned)
  • (planned)
  • (planned)
  • (planned)
  • (planned)
  • (planned)
• Ruby
  • Ruby on Rails (planned)
• Perl
  • Vanilla (planned)

(back to top)

Getting Started

Simple steps to start use the library.

Requires

Check that library works on your PHP version:

• PHP 8.0+
• Composer

Installation

Below is an simple list of step to install library.

1. Open your project directory in the terminal
2. Install package

composer require coodde/laravel-mail-checker

3. Check your composer.json file
4. Check your app.php, that ServiceProvider is installed
5. Check your config directory, that config file mail-checker.php is created

(back to top)

Usage

This table will help to understand possible usage of library and all default values:

Params	Validator classes	Validator names	Default Value	Possible Values	Description
categories	Coodde\LaravelMailChecker\Rules\MailListedValidation Coodde\LaravelMailChecker\Rules\MailValidation	mail_check_listed, mail_check	[Regions::CATEGORY_DANGEROUS]	MailListedValidator::CATEGORY_PUBLIC MailListedValidator::CATEGORY_PAID MailListedValidator::CATEGORY_TEMPORARY MailListedValidator::CATEGORY_SUSPICIOUS MailListedValidator::CATEGORY_DANGEROUS	For more comfortable usage all mail providers are split into several lists
domains	Coodde\LaravelMailChecker\Rules\MailDomainsValidation Coodde\LaravelMailChecker\Rules\MailValidation	mail_check_domains, mail_check	[]	*	Any kind of domains, starting by top level domains like "com" or "net", and finishing by exact domains like "mail.ru"
regions	Coodde\LaravelMailChecker\Rules\MailRegionsValidation Coodde\LaravelMailChecker\Rules\MailValidation	mail_check_regions, mail_check	[ Regions::RUSSIA, Regions::BELARUS, Regions::NORTH_KOREA, Regions::AFGHANISTAN, Regions::IRAN, Regions::SYRIA, Regions::SOVIET_UNION, Regions::CUBA ]	Regions::ASCENSION_ISLAND Regions::ANDORRA Regions::UNITED_ARAB_EMIRATES Regions::UAE Regions::AFGHANISTAN Regions::ANTIGUA_AND_BARBUDA Regions::ANGUILLA Regions::ALBANIA Regions::ARMENIA Regions::ANGOLA Regions::ANTARCTICA Regions::ARGENTINA Regions::AMERICAN_SAMOA Regions::AUSTRIA Regions::AUSTRALIA Regions::ARUBA Regions::ALAND Regions::AZERBAIJAN Regions::BOSNIA_AND_HERZEGOVINA Regions::BARBADOS Regions::BANGLADESH Regions::BELGIUM Regions::BURKINA_FASO Regions::BULGARIA Regions::BAHRAIN Regions::BURUNDI Regions::BENIN Regions::BERMUDA Regions::BRUNEI Regions::BOLIVIA Regions::CARIBBEAN_NETHERLANDS Regions::BRAZIL Regions::BAHAMAS Regions::BHUTAN Regions::BOTSWANA Regions::BELARUS Regions::BELIZE Regions::CANADA Regions::COCOS_ISLANDS Regions::DEMOCRATIC_REPUBLIC_OF_THE_CONGO Regions::CENTRAL_AFRICAN_REPUBLIC Regions::REPUBLIC_OF_THE_CONGO Regions::SWITZERLAND Regions::IVORY_COAST Regions::COOK_ISLANDS Regions::CHILE Regions::CAMEROON Regions::CHINA Regions::COLOMBIA Regions::COSTA_RICA Regions::CUBA Regions::CAPE_VERDE Regions::CURACAO Regions::CHRISTMAS_ISLAND Regions::CYPRUS Regions::CZECH_REPUBLIC Regions::GERMANY Regions::DJIBOUTI Regions::DENMARK Regions::DOMINICA Regions::DOMINICAN_REPUBLIC Regions::ALGERIA Regions::ECUADOR Regions::ESTONIA Regions::EGYPT Regions::WESTERN_SAHARA Regions::ERITREA Regions::SPAIN Regions::ETHIOPIA Regions::EUROPEAN_UNION Regions::FINLAND Regions::FIJI Regions::FALKLAND_ISLANDS Regions::FEDERATED_STATES_OF_MICRONESIA Regions::FAROE_ISLANDS Regions::FRANCE Regions::GABON Regions::GRENADA Regions::GEORGIA Regions::FRENCH_GUIANA Regions::GUERNSEY Regions::GHANA Regions::GIBRALTAR Regions::GREENLAND Regions::THE_GAMBIA Regions::GUINEA Regions::GUADELOUPE Regions::EQUATORIAL_GUINEA Regions::GREECE Regions::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS Regions::GUATEMALA Regions::GUAM Regions::GUINEA_BISSAU Regions::GUYANA Regions::HONG_KONG Regions::HEARD_ISLAND_AND_MCDONALD_ISLANDS Regions::HONDURAS Regions::CROATIA Regions::HAITI Regions::HUNGARY Regions::INDONESIA Regions::IRELAND Regions::ISRAEL Regions::ISLE_OF_MAN Regions::INDIA Regions::BRITISH_INDIAN_OCEAN_TERRITORY Regions::IRAQ Regions::IRAN Regions::ICELAND Regions::ITALY Regions::JERSEY Regions::JAMAICA Regions::JORDAN Regions::JAPAN Regions::KENYA Regions::KYRGYZSTAN Regions::CAMBODIA Regions::KIRIBATI Regions::COMOROS Regions::SAINT_KITTS_AND_NEVIS Regions::NORTH_KOREA Regions::SOUTH_KOREA Regions::KUWAIT Regions::CAYMAN_ISLANDS Regions::KAZAKHSTAN Regions::LAOS Regions::LEBANON Regions::SAINT_LUCIA Regions::LIECHTENSTEIN Regions::SRI_LANKA Regions::LIBERIA Regions::LESOTHO Regions::LITHUANIA Regions::LUXEMBOURG Regions::LATVIA Regions::LIBYA Regions::MOROCCO Regions::MONACO Regions::MOLDOVA Regions::MONTENEGRO Regions::MADAGASCAR Regions::MARSHALL_ISLANDS Regions::NORTH_MACEDONIA Regions::MALI Regions::MYANMAR Regions::MONGOLIA Regions::MACAU Regions::NORTHERN_MARIANA_ISLANDS Regions::MARTINIQUE Regions::MAURITANIA Regions::MONTSERRAT Regions::MALTA Regions::MAURITIUS Regions::MALDIVES Regions::MALAWI Regions::MEXICO Regions::MALAYSIA Regions::MOZAMBIQUE Regions::NAMIBIA Regions::NEW_CALEDONIA Regions::NIGER Regions::NORFOLK_ISLAND Regions::NIGERIA Regions::NICARAGUA Regions::NETHERLANDS Regions::NORWAY Regions::NEPAL Regions::NAURU Regions::NIUE Regions::NEW_ZEALAND Regions::OMAN Regions::PANAMA Regions::PERU Regions::FRENCH_POLYNESIA Regions::PAPUA_NEW_GUINEA Regions::PHILIPPINES Regions::PAKISTAN Regions::POLAND Regions::SAINT_PIERRE_AND_MIQUELON Regions::PITCAIRN_ISLANDS Regions::PUERTO_RICO Regions::PALESTINE Regions::PORTUGAL Regions::PALAU Regions::PARAGUAY Regions::QATAR Regions::RÉUNION Regions::ROMANIA Regions::SERBIA Regions::RUSSIA Regions::RWANDA Regions::SAUDI_ARABIA Regions::SOLOMON_ISLANDS Regions::SEYCHELLES Regions::SUDAN Regions::SWEDEN Regions::SINGAPORE Regions::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA Regions::SAINT_HELENA Regions::SLOVENIA Regions::SLOVAKIA Regions::SIERRA_LEONE Regions::SAN_MARINO Regions::SENEGAL Regions::SOMALIA Regions::SURINAME Regions::SOUTH_SUDAN Regions::SAO_TOME_AND_PRINCIPE Regions::SOVIET_UNION Regions::EL_SALVADOR Regions::SINT_MAARTEN Regions::SYRIA Regions::ESWATINI Regions::TURKS_AND_CAICOS_ISLANDS Regions::CHAD Regions::FRENCH_SOUTHERN_AND_ANTARCTIC_LANDS Regions::TOGO Regions::THAILAND Regions::TAJIKISTAN Regions::TOKELAU Regions::EAST_TIMOR Regions::TURKMENISTAN Regions::TUNISIA Regions::TONGA Regions::TURKEY Regions::TRINIDAD_AND_TOBAGO Regions::TUVALU Regions::TAIWAN Regions::TANZANIA Regions::UKRAINE Regions::UGANDA Regions::UNITED_KINGDOM Regions::UNITED_STATES_OF_AMERICA Regions::USA Regions::URUGUAY Regions::UZBEKISTAN Regions::VATICAN_CITY Regions::SAINT_VINCENT_AND_THE_GRENADINES Regions::VENEZUELA Regions::BRITISH_VIRGIN_ISLANDS Regions::UNITED_STATES_VIRGIN_ISLANDS Regions::VIETNAM Regions::VANUATU Regions::WALLIS_AND_FUTUNA Regions::SAMOA Regions::YEMEN Regions::MAYOTTE Regions::SOUTH_AFRICA Regions::ZAMBIA Regions::ZIMBABWE	Recommended to use constants for easier code maintenance

Here you will find different cases of usage.

Checking that mail address registered in Russian mail provider:

use Coodde\LaravelMailChecker\Rules\MailRegionsValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => ['required', new MailRegionsValidation([Regions::RUSSIA])],
    ]);
 
    // OR with configs from env, ex. (country code) - MAIL_CHECKER_REGIONS=ru

    $validated = $request->validate([
        'email' => ['required', new MailRegionsValidation()],
    ]);
 
    // Request is valid...
 
    return redirect('/list');
}

Checking that mail address registered in "ru" or "mail.by" domains:

use Coodde\LaravelMailChecker\Rules\MailDomainsValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => ['required', new MailDomainsValidation(['ru', 'mail.by'])],
    ]);
 
    // OR with configs from env, ex. - MAIL_CHECKER_DOMAINS=ru,mail.by

    $validated = $request->validate([
        'email' => ['required', new MailDomainsValidation()],
    ]);

    // Request is valid...
 
    return redirect('/list');
}

Checking that mail address is placed in dangerous or suspicious lists:

use Coodde\LaravelMailChecker\Rules\MailListedValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => ['required', new MailListedValidation([MailListedValidation::CATEGORY_DANGEROUS, MailListedValidation::CATEGORY_SUSPICIOUS])],
    ]);

    // OR with configs from env, ex. - MAIL_CHECKER_CATEGORIES=dangerous,suspicious

    $validated = $request->validate([
        'email' => ['required', new MailListedValidation()],
    ]);
 
    // Request is valid...
 
    return redirect('/list');
}

Complex validation to allow only corporate emails, :

use Coodde\LaravelMailChecker\Rules\MailValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => [
        	'required',
        	new MailValidation(
        		[
        			MailListedValidation::CATEGORY_DANGEROUS,
        			MailListedValidation::CATEGORY_SUSPICIOUS,
        			MailListedValidation::CATEGORY_TEMPORARY,
        			MailListedValidation::CATEGORY_PAID,
        			MailListedValidation::CATEGORY_PUBLIC,
        		],
        		[
        			'fb.com',
        		],
        		[
        			Regions::RUSSIA,
        			Regions::BELARUS,
        		],
        	),
       	],
    ]);

    // OR with separate validators

    $validated = $request->validate([
        'email' => [
        	'required',
        	new MailListedValidation([
    			MailListedValidation::CATEGORY_DANGEROUS,
    			MailListedValidation::CATEGORY_SUSPICIOUS,
    			MailListedValidation::CATEGORY_TEMPORARY,
    			MailListedValidation::CATEGORY_PAID,
    			MailListedValidation::CATEGORY_PUBLIC,
        	]),
        	new MailDomainsValidation([
    			'fb.com',
    		]),
        	new MailRegionsValidation([
    			Regions::RUSSIA,
    			Regions::BELARUS,
    		]),
       	],
    ]);
 
    // Request is valid...
 
    return redirect('/list');
}

Of course you can combine restrictioned domains, countries, and categories

(back to top)

Roadmap

• Checking by countries
• Checking by domains
• Prepared lists
  • Dangerous - usually scaming servers / domains
  • Suspicios - usually spaming servers / domains
  • Paid - mail providers with non-free subscription
  • Temporary - services for mails which will be removed soon after creation
  • Public - popular free services like gmail, outlook, etc
• Checking by prepaired lists
  • From files - it uses binary search without file content buffering
  • From cache - cache files with lists compiled into php file
  • From memory - storing lists in memcache
  • From database - by using PDO library+

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

✅ Run refactors using Rector

composer refacto

⚗️ Run static analysis using PHPStan:

composer test:types

✅ Run unit tests using PEST

composer test:unit

🚀 Run the entire test suite:

composer test

Top contributors:

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

Contact

Svyatoslav Ryzhok - [email protected]

Platform Link: https://coodde.com

(back to top)