Search by

arraypress / wp-email-utils

arraypress

An immutable value object for working with email addresses in WordPress — parsing, validation, transformation, classification and analysis.

Package info

github.com/arraypress/wp-email-utils

pkg:composer/arraypress/wp-email-utils

Statistics

Installs: 187

Dependents: 1

Suggesters: 0

Stars: 1

Open Issues: 0

v1.0.0 2026-08-25 15:44 UTC

This package is auto-updated.

Last update: 2026-11-18 10:51:16 UTC


README

This library has moved. It is now part of sugarcommerce/network (namespace SugarCommerce\Network, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.

WordPress Email Utilities

An email address as a value object, so the fiddly questions have answers.

What it does

is_email() tells you whether an address is syntactically valid. Almost every real question is a different one: are dave+shop@gmail.com and d.a.v.e@gmail.com the same person signing up twice, is info@ a role mailbox rather than a human, did someone type gmial.com, does the domain accept mail at all.

Parse once into an Email, then ask. It is immutable, so the transformations hand back a new instance rather than changing the one you have.

Features

  • Compare two addresses as the same person, ignoring subaddresses and Gmail dots
  • Spot role mailboxes — info@, sales@, admin@ — that are not individuals
  • Catch common domain typos and suggest the correction
  • Check the domain actually has an MX record before accepting a signup
  • Recognise educational and government addresses, for discounts or verification
  • Add, replace or strip a +tag subaddress
  • Mask an address for display: d••••e@example.com
  • Match against wildcard patterns, for allow and block lists
  • List every domain and ending a rule about an address could name: mail.example.co.uk, example.co.uk; uk, co.uk
  • Pull the host out of whatever was pasted where a domain goes: an address, a URL, @example.com

Installation

composer require arraypress/wp-email-utils

Quick start

use ArrayPress\EmailUtils\Email;

$email = Email::parse( $_POST['email'] );

if ( ! $email ) {
    return new WP_Error( 'invalid_email', 'That address is not valid.' );
}

// Did they mean gmail.com?
if ( $email->has_typo() ) {
    $suggestion = $email->suggested_email();
}

// Is this the same customer signing up again with a +tag?
if ( $email->equals_base( $existing_customer_email ) ) {
    // ...
}

// Route role mailboxes differently from real people.
if ( $email->is_role_based() ) {
    // ...
}

// Show it in the admin without showing all of it.
echo esc_html( $email->to_masked() );

// Show it to somebody who may not be its owner: first character, a fixed
// run, the domain. "p••@example.com", whatever the length of the name.
echo esc_html( Email::mask( 'patricia@example.com' ) );

The domain helpers are static and take a string, so an address too odd to validate still has a domain to check. Email::domain_parents(), Email::domain_suffixes(), Email::host_from() and Email::is_hostname() know nothing of the public suffix list, and convert nothing between an internationalised name and its xn-- form: the xn-- form is a host name here and the Unicode one is not, as with is_email().

Requirements

  • PHP 8.3 or later
  • WordPress 7.1 or later

License

GPL-2.0-or-later