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: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/ashallendesign/email-utilities

v0.1.0 2025-10-08 22:50 UTC

Requires

Requires (Dev)

MIT 811fcbaf55de2eb8f85e19d62577d58059932329

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

emaillaravelashallendesignemail-utilities

This package is auto-updated.

Last update: 2025-10-08 22:52:33 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

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

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.

Upgrading

Check the UPGRADE guide to get more information on how to update this library to newer versions.

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