ashallendesign/email-utilities

A Laravel package containing some useful utilities for working with email addresses.

Maintainers

Details

github.com/ash-jc-allen/email-utilities

Homepage

Source

Issues

Fund package maintenance!
ash-jc-allen

Installs: 121

Dependents: 0

Suggesters: 0

Security: 0

Stars: 23

Watchers: 0

Forks: 1

Open Issues: 1

pkg:composer/ashallendesign/email-utilities

v1.0.0 2025-10-27 17:28 UTC

Requires

Requires (Dev)

MIT c958f7e3dadf9106bb65c579971f9ccfbb8c91a2

  • Ash Allen <mail.woop@ashallendesign.co.uk>

emaillaravelashallendesignemail-utilities

This package is auto-updated.

Last update: 2025-10-29 10:24:28 UTC

README

Email Utilities

Latest Version on Packagist Total Downloads PHP from Packagist GitHub license

Table of Contents

Overview

A small Laravel package that can be used for interacting with email addresses.

Installation

Requirements

The package has been developed and tested to work with the following minimum requirements:

  • PHP 8.4
  • Laravel 12.0

Install the Package

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 php artisan vendor:publish --tag=email-utilities-config

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

Usage

The Email Class

The 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('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 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.

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

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

Testing

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

Security

If you find any security related issues, please contact me directly at mail@ashallendesign.co.uk to report it.

Contribution

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:

  • Write tests for any new functions that are added. If you are updating existing code, make sure that the existing tests pass and write more if needed.
  • Follow PSR-12 coding standards.
  • Make all pull requests to the main branch.

Changelog

Check the CHANGELOG to get more information about the latest changes.

Credits

License

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

Support Me

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.

👉 Get Your Copy!

Battle Ready Laravel