Download the PHP package utopia-php/emails without Composer

Utopia Emails

Utopia Emails library is a simple and lite library for parsing and validating email addresses. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.

Although this library is part of the Utopia Framework project, it can be used as standalone with any other PHP project or framework.

Getting Started

Install using composer:

Library API

Email Class

Constants

The Email class provides the following constants for email formatting:

• Email::FORMAT_FULL - Full email address (default)
• Email::FORMAT_LOCAL - Local part only (before @)
• Email::FORMAT_DOMAIN - Domain part only (after @)
• Email::FORMAT_PROVIDER - Provider domain (domain without subdomain)
• Email::FORMAT_SUBDOMAIN - Subdomain part only

Methods

• get() - Return full email address.
• getLocal() - Return local part (before @).
• getDomain() - Return domain part (after @).
• isValid() - Check if email is valid format.
• hasValidLocal() - Check if email has valid local part.
• hasValidDomain() - Check if email has valid domain part.
• isDisposable() - Check if email is from a disposable email service.
• isFree() - Check if email is from a free email service.
• isCorporate() - Check if email is from a corporate domain.
• getProvider() - Get email provider (domain without subdomain).
• getSubdomain() - Get email subdomain (if any).
• hasSubdomain() - Check if email has subdomain.
• getFormatted(string $format) - Get email in different formats. Use constants: Email::FORMAT_FULL, Email::FORMAT_LOCAL, Email::FORMAT_DOMAIN, Email::FORMAT_PROVIDER, Email::FORMAT_SUBDOMAIN.

Using the Validators

Library Validators API

• Email - Basic email validation using the Email class.
• EmailDomain - Validates that an email address has a valid domain.
• EmailLocal - Validates that an email address has a valid local part.
• EmailNotDisposable - Validates that an email address is not from a disposable email service.
• EmailCorporate - Validates that an email address is from a corporate domain (not free or disposable).

Email Classification

The library automatically classifies emails into three categories:

Free Email Services

Common free email providers like Gmail, Yahoo, Hotmail, Outlook, etc.

Disposable Email Services

Temporary email services like 10minutemail, GuerrillaMail, Mailinator, etc.

Corporate Email Services

All other email addresses that are not classified as free or disposable.

Supported Email Formats

The library supports various email formats including:

• Basic: [email protected]
• With dots: [email protected]
• With plus: [email protected]
• With hyphens: [email protected]
• With underscores: [email protected]
• With numbers: [email protected]
• With subdomains: [email protected]
• With multiple subdomains: [email protected]

Validation Rules

Local Part (before @)

• Maximum 64 characters
• Can contain letters, numbers, dots, underscores, hyphens, and plus signs
• Cannot start or end with a dot
• Cannot contain consecutive dots

Domain Part (after @)

• Maximum 253 characters
• Must contain at least one dot
• Must have a valid TLD (at least 2 characters)
• Can contain letters, numbers, dots, and hyphens
• Cannot start or end with a dot or hyphen
• Cannot contain consecutive dots or hyphens

Data Management & Import System

The library uses external data files to classify email domains as free or disposable. These files are located in the data/ directory:

• data/free-domains.php - List of known free email service providers
• data/disposable-domains.php - List of known disposable/temporary email services
• data/free-domains-manual.php - Manually managed free email domains
• data/disposable-domains-manual.php - Manually managed disposable email domains

Import System

The library includes a comprehensive import system that can automatically update domain lists from multiple sources.

Quick Start

Available Commands

Update All Domains

Update Disposable Domains Only

Update Free Domains Only

Show Statistics

Composer Scripts

For convenience, you can also use composer scripts:

Import Sources

Disposable Email Sources:

• Manual Disposable Email Domains (configurable)
• Martenson Disposable Email Domains
• Disposable Email Domains
• Wes Bos Burner Email Providers
• 7c FakeFilter Domains
• Adam Loving Temporary Email Domains

Free Email Sources:

• Manual Free Email Domains (configurable)

Features

• Multiple Sources: Support for 5+ disposable email domain sources
• Manual Configuration: Ability to manually manage both free and disposable email domains
• Domain Validation: Built-in domain validation using Utopia Domains
• Statistics & Analysis: Detailed domain statistics and TLD analysis
• Deduplication: Automatic removal of duplicate domains
• Error Handling: Robust error handling with graceful fallbacks

Manual Domain Management

You can manually edit the domain files to add or remove domains:

Free Email Domains - Edit data/free-domains-manual.php:

Disposable Email Domains - Edit data/disposable-domains-manual.php:

Configuration

Sources are defined in import.php. You can:

• Enable/disable sources by modifying the source arrays
• Add new sources by adding entries to the DISPOSABLE_SOURCES or FREE_SOURCES arrays
• Modify existing source URLs or descriptions

System Requirements

Utopia Emails requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.

Authors

Eldad Fux

• https://twitter.com/eldadfux
• https://github.com/eldadfux

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php