Email Utilities for Laravel v1.0 Released!

Introduction

A common feature I often need to build for public-facing forms is to prevent users from submitting forms with email addresses from disposable providers. These services provide temporary email addresses that can be used for a short time before being discarded.

For example, when somebody signs up for my newsletter, they receive a free copy of my "Clean Coder's Guide to Laravel" PDF. But I found that some people were using disposable email addresses to sign up, download the PDF, and then discard the email address. This meant I then had a bunch of invalid email addresses in my mailing list, which isn't ideal.

To solve this problem, in addition to using other techniques such as double opt-in and stronger email validation, I prevent users from signing up with disposable email addresses. I then found myself copying this same feature into multiple projects, so I decided to create a reusable package that I could use instead: Email Utilities for Laravel.

In this article, I'll give an overview of what the package does and how to use it in your Laravel projects.

If you're interested in checking out the package, you can find it on GitHub here: https://github.com/ash-jc-allen/email-utilities

Please note that, at the time of writing this article, this package does not validate whether an email address is valid or not. It is intended to be used in conjunction with Laravel's built-in email validation rule. This package simply provides some additional utilities for working with email addresses that I have needed in multiple projects.

Installation

To install the package, you'll need to be using at least PHP 8.3 and Laravel 11.0.

You can install the package via Composer by running the following command in your project's root directory:

composer require ashallendesign/email-utilities

After installing the package, you can then publish the configuration file using the following command:

php artisan php artisan vendor:publish --tag=email-utilities-config

Running this command will create a config/email-utilities.php file.

The "Email" Class

The package provides an AshAllenDesign\EmailUtilities\Email class for interacting 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('hello@example.com');

Disposable Email Addresses

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('hello@0-mail.com')->isDisposable(); // true
new Email('hello@laravel.com')->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 created all the time, so some disposable email addresses may not be detected. So please use this functionality with that in mind.

Role-based Email Addresses

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('sales@example.com')->isRoleAccount(); // true
new Email('ash@example.com')->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.

Checking the Domain of an Email Address

"domainIs" Method

The AshAllenDesign\EmailUtilities\Email class also provides a domainIs method that checks 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('hello@example.com')->domainIs(['example.com']); // true
new Email('hello@example.com')->domainIs(['example.com', 'test.com']); // true
new Email('hello@example.com')->domainIs(['example*']); // true
new Email('hello@example.com')->domainIs(['ex*le.com']); // true
new Email('hello@example.com')->domainIs(['ex*le.com']); // true

new Email('hello@example.com')->domainIs(['example']); // false
new Email('hello@example.com')->domainIs(['test.com']); // false

"domainIsNot" Method

Similarly, 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('hello@example.com')->domainIsNot(['example.com']); // false
new Email('hello@example.com')->domainIsNot(['example.com', 'test.com']); // false
new Email('hello@example.com')->domainIsNot(['example*']); // false
new Email('hello@example.com')->domainIsNot(['ex*le.com']); // false
new Email('hello@example.com')->domainIsNot(['ex*le.com']); // false

new Email('hello@example.com')->domainIsNot(['example']); // true
new Email('hello@example.com')->domainIsNot(['test.com']); // true

Validation Rules

Please note that the validation rules 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 email validation rule (https://laravel.com/docs/12.x/validation#rule-email).

"EmailDomainIs" Rule

The 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" Rule

Similar 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()],
]);

Config

The package provides several options that can be configured via the published configuration file located at config/email-utilities.php.

Disposable Email Domains List

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/app/disposable_email_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.

Role Accounts List

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',

Check Out the Package