PHP Mail Checker

This package provides simple checker for emails, to validate mail providers.

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
  • Vanilla
  • 
  • 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/mail-checker

3. Check your composer.json file

(back to top)

Usage

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

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

$mailChecker = new MailChecker([], [], [Regions::RUSSIA]);

// This will return boolean value
$result = $mailChecker->allowed('test@gmail.com');
// or
$result = $mailChecker->forbidden('test@mail.ru');

// Also you can catch exception
try {
  $mailChecker->validate('test@mail.ru');
} catch (RegionMailCheckException $e) {
  echo "Forbidden region";
} catch (MailCheckException $e) {
  echo "Wrong mail format (not validated before checking)";
} catch (\Exception $e) {
  echo "Unhandled exception";
}

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

use Coodde\MailChecker\MailChecker;
use Coodde\MailChecker\Regions;
use Coodde\MailChecker\Exceptions\MailCheckException;
use Coodde\MailChecker\Exceptions\DomainMailCheckException;
use Coodde\MailChecker\Exceptions\ListingMailCheckException;
use Coodde\MailChecker\Exceptions\RegionMailCheckException;

$mailChecker = new MailChecker([], ['ru', 'mail.by'], []);

// This will return boolean value
$result = $mailChecker->allowed('test@gmail.com');
// or
$result = $mailChecker->forbidden('test@test.ru');
$result = $mailChecker->forbidden('test@mail.by');

// Also you can catch exception
try {
  $mailChecker->validate('test@mail.ru');
} catch (DomainMailCheckException $e) {
  echo "Forbidden domain";
} catch (MailCheckException $e) {
  echo "Wrong mail format (not validated before checking)";
} catch (\Exception $e) {
  echo "Unhandled exception";
}

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

use Coodde\MailChecker\MailChecker;
use Coodde\MailChecker\Regions;
use Coodde\MailChecker\Exceptions\MailCheckException;
use Coodde\MailChecker\Exceptions\ListingMailCheckException;

$mailChecker = new MailChecker([MailChecker::CATEGORY_DANGEROUS, MailChecker::CATEGORY_SUSPICIOUS], [], []);

// This will return boolean value
$result = $mailChecker->allowed('test@gmail.com');
// or
$result = $mailChecker->forbidden('test@gmail.ru');

// Also you can catch exception
try {
  $mailChecker->validate('test@gmail.ru');
} catch (ListingMailCheckException $e) {
  echo "Dangerous mail provider";
} catch (MailCheckException $e) {
  echo "Wrong mail format (not validated before checking)";
} catch (\Exception $e) {
  echo "Unhandled exception";
}

Alternative way to configure restrictions:

$mailChecker = new MailChecker();

// Forbid countries
$mailChecker->forbidRegions([Regions::RUSSIA]);

// Forbid categories
$mailChecker->forbidCategories([
  MailChecker::CATEGORY_PAID,
  MailChecker::CATEGORY_TEMPORARY,
]);

// Forbid domains
$mailChecker->forbidDomains(['mail.ru']);

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

(back to top)

Roadmap

• Checking by countries
• Checking by domains
• Prepared lists
  • Paid - mail providers with non-free subscription
  • Dangerous - usually spaming servers / domains
  • Public - popular free services like gmail, outlook, etc
  • Temporary - services for mails which will be removed soon after creation
• 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 MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Svyatoslav Ryzhok - info@coodde.com

Platform Link: https://coodde.com

(back to top)