Download the PHP package rlnks/php-mail-audit without Composer

php-mail-audit

Email HTML quality analysis engine for PHP.

Analyze email templates before sending — detect compatibility issues, score your HTML against major email clients, and get actionable insights to fix problems before they reach your users' inboxes.

"Grammarly for HTML emails"

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• Analyzing HTML
• Result Format
• Bundled Rules
• Detection Types
• Localization
• Remote KB Sync
• CLI
• Custom Rules
• Custom Detectors
• Score Calculation
• Integration Examples
• Running Tests
• License

Requirements

• PHP 8.1 or higher
• No external dependencies — uses PHP's native DOMDocument
• No framework required — works with Laravel, Symfony, Slim, or plain PHP

Installation

Quick Start

Example output:

Configuration

All configuration is optional. The package works out of the box with the bundled rule set.

Config reference

Config file pattern

Analyzing HTML

Pass the raw HTML string of the email template. The HTML does not need to be a complete document — partials and fragments are accepted.

Result Format

analyze() returns an array with four keys:

score

An integer between 0 and 100. Higher is better. See Score Calculation.

insights

Each triggered rule produces one insight:

Each location entry points to one occurrence of the issue in the source HTML:

This is designed for editor integration — use offset_start/offset_end with CodeMirror or Monaco Range objects to highlight the exact positions, and line/column to scroll and place the cursor.

When multiple locales are requested, message and fix are associative arrays keyed by locale instead of strings:

passed

Rules that did not trigger and carry a success_message appear here — useful for showing positive feedback alongside issues (similar to htmlemailcheck.com):

Not every rule generates a passed item — only rules that define a success_message in their JSON (those where the absence of an issue is meaningfully good news).

summary

Bundled Rules

56 rules ship with the package. The philosophy: flag bad usage, not feature presence. Media queries, hover states, and class selectors used correctly (with inline fallbacks) score well. The engine penalizes the absence of fallbacks, not the features themselves.

Errors — break rendering in major clients

Warnings — real problems when fallbacks are missing

Info — usage noted, minimal score impact

Rules in this category flag the presence of a feature that is often used correctly as progressive enhancement. They fire when the feature is detected, regardless of fallback quality — the corresponding warning-level rules handle the bad cases.

Detection Types

Every rule declares a detection object that specifies how the engine finds the issue. All detectors return exact character positions (line, column, byte offsets) for every match — see locations in the result format.

css_property

Matches CSS patterns anywhere in the document — inline style="" attributes and <style> blocks.

Supports optional "regex": true for patterns that require precision (e.g. to avoid false positives with similar property names):

html_tag

Fires when the specified HTML tag is present at least once. Uses DOMDocument for accurate parsing.

Patterns are tag names (no angle brackets).

html_attribute_missing

Fires when at least one instance of tag is missing a required attribute, or has an attribute with the wrong value.

With value check:

With "only_empty": true — fires when the attribute is present but empty (alt=""). Useful for distinguishing missing alt text from intentionally empty alt text:

html_content

Matches arbitrary string patterns anywhere in the raw HTML string.

Supports "regex": true for patterns requiring precision. The ~ character is used as the regex delimiter internally — escape it as \\~ if needed in a pattern:

html_tag_with_style

Fires when a tag is present and its inline style attribute contains one of the given CSS patterns. Useful for distinguishing structural divs from decorative ones.

Supports "regex": true for precise matching (e.g. to avoid matching max-width: when looking for width:):

correlation

Fires when a trigger pattern is present but an expected fallback pattern is absent. Use this to flag bad usage of a feature rather than its mere presence.

The rule above fires only when an external font is loaded and no inline font-family fallback stack is found — correctly scoring emails that use custom fonts with proper fallbacks.

style_block

Searches exclusively inside <style> block content. Supports plain strings or regular expressions.

With regex:

preheader

Detects the standard email preheader pattern — a <div> with both display:none and overflow:hidden in its inline style. Two modes:

• missing — fires when no preheader div is found in a complete document (one that contains a <body> tag). Fragments are skipped.
• too_long — fires when the visible preheader text exceeds max_length characters. Filler characters ( , ‌, and their Unicode equivalents) are stripped before measuring, so filling with spacers does not inflate the count.

html_metric

Measures a numeric property of the HTML and fires when it exceeds a threshold. Currently supported metrics:

heading_order

Detects heading levels that are skipped in document order (e.g. <h1> directly followed by <h3>). No configuration options.

html_link_no_text

Fires when an <a> element has no accessible text — no text node content and no child <img> with a non-empty alt. No configuration options.

html_tracking_pixel

Detects <img> elements with width="1" and height="1", the classic open-tracking pattern. No configuration options.

css_font_family

Detects multi-word font names used without quotes in font-family declarations (e.g. font-family: Open Sans instead of font-family: 'Open Sans'). No configuration options.

html_table_width

Fires when a <table> element carries an inline width in pixels that exceeds max_width (default: 600).

Localization

Five locales are bundled: en (English), fr (French), es (Spanish), de (German), pt (Portuguese).

Single locale

If a locale is missing for a rule, it falls back to en automatically.

Multiple locales

Pass an array to receive all translations in a single pass:

This is useful when building multi-language UIs without running analyze() twice.

Adding a locale

Add the locale key to message, fix, and optionally success_message in each rule JSON:

Remote KB Sync

By default the package uses the bundled rule set. You can point it at a remote endpoint to receive updated rules without a Composer update.

How it works

Enabling sync

Tier behavior

Cache behavior

CLI

A command-line tool is available at vendor/bin/mailaudit after installation.

sync — refresh the local cache

Using environment variables:

Using a config file:

Dry run (fetch but do not write cache):

Available options

Environment variables

audit — analyze an email file

Example output (text):

With --format=json, the full analyze() result array is printed as pretty-printed JSON — same structure as documented in Result Format.

audit options

Custom Rules

You can add your own rules without modifying the package.

1. Create a rule JSON file

2. Load it alongside the bundled rules

Or subclass MailAudit to make this reusable in your project.

Rule JSON reference

Custom Detectors

You can register new detection types to support custom rule patterns.

1. Implement DetectorInterface

2. Register it with the factory

3. Use it in a rule JSON

Registration is global and static — register once at application bootstrap before calling analyze().

Score Calculation

The score starts at 100. Each triggered rule deducts a weighted amount based on its severity:

Example:

The score cannot go below 0.

Severity vs weight

Severity (error, warning, info) is a qualitative label indicating the nature of the problem. Weight is the nominal importance of the rule. The multiplier ensures that warnings and info items have a proportionally smaller impact on the score than blocking errors, so a well-crafted email with minor compatibility caveats scores realistically (75–90) rather than being penalized alongside fundamentally broken emails.

Integration Examples

Vanilla PHP

Symfony

Laravel

In a CI/CD pipeline (GitHub Actions)

Running Tests

Run static analysis:

License

MIT — © 2026 rlnks