A Laravel package containing some useful utilities for working with email addresses.
ashallendesign/email-utilities is a Laravel package for a laravel package containing some useful utilities for working with email addresses..
It currently has 132 GitHub stars and 24.610 downloads on Packagist (latest version v1.2.0).
Install it with composer require ashallendesign/email-utilities.
Discover more Laravel packages by ashallendesign
or browse all Laravel packages to compare alternatives.
Last updated
A small Laravel package that can be used for interacting with email addresses.
The package has been developed and tested to work with the following minimum requirements:
You can install the package via Composer:
composer require ashallendesign/email-utilities
After installing the package, you can then publish the configuration file using the following command:
php artisan vendor:publish --tag=email-utilities-config
Running this command will create a config/email-utilities.php file.
Email ClassThe package provides an AshAllenDesign\EmailUtilities\Email class that can be used to interact with email addresses.
You can create a new instance of it by passing an email address to the constructor:
use AshAllenDesign\EmailUtilities\Email;
$email = new Email('[email protected]');
You can check whether a given email address is deemed to be disposable/temporary (meaning it's provided by a disposable email address provider) by using the isDisposable() method:
use AshAllenDesign\EmailUtilities\Email;
new Email('[email protected]')->isDisposable(); // true
new Email('[email protected]')->isDisposable(); // false
The package's list of disposable domains is defined in the AshAllenDesign\EmailUtilities\Lists\DisposableDomainList class. You can output a list of all the disposable email address domains by using the get() method:
use AshAllenDesign\EmailUtilities\Lists\DisposableDomainList;
$disposableEmailDomains = DisposableEmailDomains::get();
// [
// '0-mail.com',
// '027168.com',
// '062e.com',
// ...
// ]
The list of disposable email address providers is sourced from https://github.com/disposable-email-domains/disposable-email-domains. It's worth remembering that new domains are being used all the time, so it's possible that some disposable email addresses may not be detected. So please use this functionality with that in mind.
[!NOTE] If you wish to keep the list of disposable email domains up-to-date, please check the Usage > Commands > Updating the Disposable Email Domains List section below. The package provides a handy
FetchDisposableEmailDomainsArtisan command which you can schedule.
You may want to check whether a given email address is role-based. Role-based email addresses are those that are not specific to an individual, but rather to a role or function within an organisation. Examples include admin@, support@, info@ and sales@.
To do this, you can use the isRoleAccount() method:
use AshAllenDesign\EmailUtilities\Email;
new Email('[email protected]')->isRoleAccount(); // true
new Email('[email protected]')->isRoleAccount(); // false
Similar to the disposable email address domains, the package's list of role-based email address prefixes is defined in the AshAllenDesign\EmailUtilities\Lists\RoleAccountList class. You can output a list of all the role-based email address prefixes by using the get() method:
use AshAllenDesign\EmailUtilities\Lists\RoleAccountList;
$roleAccountList = RoleAccountList::get();
// [
// 'admin',
// 'administrator',
// 'contact',
// ...
// ]
Please remember that this list is not exhaustive, so it may not detect all role-based email-addresses.
domainIs MethodThe AshAllenDesign\EmailUtilities\Email class also provides a domainIs method which can be used to check whether the domain of an email address matches a given pattern. This is useful if you want to check whether an email address belongs to a specific domain or set of domains.
The beauty of this method is that it supports wildcard (*) patterns, so it allows for more flexible matching.
For example:
use AshAllenDesign\EmailUtilities\Email;
new Email('[email protected]')->domainIs(['example.com']); // true
new Email('[email protected]')->domainIs(['example.com', 'test.com']); // true
new Email('[email protected]')->domainIs(['example*']); // true
new Email('[email protected]')->domainIs(['ex*le.com']); // true
new Email('[email protected]')->domainIs(['ex*le.com']); // true
new Email('[email protected]')->domainIs(['example']); // false
new Email('[email protected]')->domainIs(['test.com']); // false
domainIsNot MethodSimilarly, the AshAllenDesign\EmailUtilities\Email class also provides a domainIsNot method which can be used to check whether the domain of an email address does not match a given pattern.
For example:
use AshAllenDesign\EmailUtilities\Email;
new Email('[email protected]')->domainIsNot(['example.com']); // false
new Email('[email protected]')->domainIsNot(['example.com', 'test.com']); // false
new Email('[email protected]')->domainIsNot(['example*']); // false
new Email('[email protected]')->domainIsNot(['ex*le.com']); // false
new Email('[email protected]')->domainIsNot(['ex*le.com']); // false
new Email('[email protected]')->domainIsNot(['example']); // true
new Email('[email protected]')->domainIsNot(['test.com']); // true
[!NOTE] Please note, the validation rules that are included with this package don't validate that a value is actually an email address. These rules are intended to be used in conjunction with Laravel's built-in
EmailDomainIs RuleThe package provides an AshAllenDesign\EmailUtilities\Rules\EmailDomainIs validation rule that can be used to validate that the domain of an email address matches a given pattern. This is useful if you want to ensure that an email address belongs to a specific domain or set of domains, such as only allowing email addresses from your own organisation.
It uses the AshAllenDesign\EmailUtilities\Email::domainIs method under the hood, so it supports wildcard (*) patterns.
You can use the rule like so:
use AshAllenDesign\EmailUtilities\Rules\EmailDomainIs;
$request->validate([
'email' => ['required', 'email', new EmailDomainIs(patterns: ['example.com', '*.example.com'])],
]);
In this particular example, we've hardcoded the allowed domain pattern, but you may want to load this from a configuration file or the database instead.
EmailDomainIsNot RuleSimilar to the EmailDomainIs rule, the package also provides an AshAllenDesign\EmailUtilities\Rules\EmailDomainIsNot validation rule that can be used to validate that the domain of an email address does not match a given pattern. This is useful if you want to ensure that an email address does not belong to a specific domain, such as a list of known disposable email address providers.
You can use the rule like so:
use AshAllenDesign\EmailUtilities\Rules\EmailDomainIsNot;
$request->validate([
'email' => ['required', 'email', new EmailDomainIsNot(patterns: ['disposable.com', '*.disposable.com'])],
]);
This validation rule also comes with a handy disposable method so you can quickly add a rule to prevent disposable email addresses from being used:
use AshAllenDesign\EmailUtilities\Rules\EmailDomainIsNot;
$request->validate([
'email' => ['required', 'email', EmailDomainIsNot::disposable()],
]);
As mentioned above, the package comes with a built-in list of disposable email address domains. However, new disposable email address providers are being created all the time, so it's important to keep this list up-to-date. Generally, there are three ways you can do this:
FetchDisposableEmailDomains Artisan command to automatically fetch and store the latest list of disposable email address domains.You can run the FetchDisposableEmailDomains command like so:
php artisan email-utilities:fetch-disposable-domains
This command will fetch the latest list of disposable email address domains from https://github.com/disposable-email-domains/disposable-email-domains and store the list in the location defined by the disposable_email_list_path configuration option.
Please note, you must set the dispoable_email_list_path configuration option for this to work. If this option is left as null (the default value), the list will not be fetched.
You may want to schedule this command to run on a regular basis to ensure that your list of disposable email address domains is always up-to-date. You can do this in your routes/console.php file like so:
Schedule::command(\AshAllenDesign\EmailUtilities\Commands\FetchDisposableEmailDomains::class)
->daily()
->emailOutputOnFailure('[email protected]');
The package provides several options that can be configured via the published configuration file located at config/email-utilities.php.
By default, the package uses a built-in list of disposable email address domains defined in the AshAllenDesign\EmailUtilities\Lists\DisposableDomainList class. Over time, this list may change as new disposable email address providers are created.
However, you can maintain your own list of disposable domains by setting the disposable_email_list_path configuration option like so:
'disposable_email_list_path' => storage_path('app/disposable-domains.json'),
You can also publish the package's built-in list to your application by running the following command:
php artisan vendor:publish --tag=email-utilities-lists
This will create a disposable-domains.json file in your application's root directory. You can then modify this file as needed and update the disposable_email_list_path configuration option to point to this file. Running this command will also publish a role-accounts.json file that you can use to maintain your own list of role-based email address prefixes.
Similar to the disposable email domains list, by default, the package uses a built-in list of role-based email address prefixes defined in the AshAllenDesign\EmailUtilities\Lists\RoleAccountList class. However, you can maintain and provide your own list by setting the role_account_list_path configuration option like so:
'role_accounts_list_path' => './storage/app/role_account_list.json',
To run the package's unit tests, run the following command:
composer test
To run Larastan for the package, run the following command:
composer larastan
If you find any security related issues, please contact me directly at [email protected] to report it.
If you wish to make any changes or improvements to the package, feel free to make a pull request.
To contribute to this package, please use the following guidelines before submitting your pull request:
main branch.Check the CHANGELOG to get more information about the latest changes.
The MIT License (MIT). Please see License File for more information.
If you've found this package useful, please consider buying a copy of Battle Ready Laravel to support me and my work.
Every sale makes a huge difference to me and allows me to spend more time working on open-source projects and tutorials.
To say a huge thanks, you can use the code BATTLE20 to get a 20% discount on the book.
