email-accessibility-checker

Email Accessibility Checker

Analyze email HTML for accessibility issues. Combines mechanical rule-based checks with judgment-based analysis to catch issues that rules alone miss.

Token efficiency: Only report issues found. Do not list passing checks or clean elements. If the email is long, prioritize critical and serious issues first.

Severity must reflect impact, not fix complexity. Assign severity based on how much the issue affects people using assistive technology — not how easy it is to fix. A finding described as "invisible", "unreadable", or "critically low contrast" must never be assigned mild or moderate. If the language you use to describe the problem contradicts the severity label, the label is wrong.

Workflow

Step 1: Get the HTML

Obtain the final email HTML to analyze. This may be provided directly by the user, read from a file, or fetched from an API.

Before scanning: Rendered HTML often splits element attributes across multiple lines. Before running any checks, flatten the HTML so each opening tag is a single logical line — attributes on continuation lines will be silently missed by line-by-line grep patterns. When using shell tools, collapse newlines within tags before grepping (e.g. tr '\n' ' ' then sed 's/ */ /g'). When analyzing directly, always read the complete opening tag and its full text content before evaluating.

Step 2: Rule-based checks

Scan the HTML for these mechanical pass/fail issues. Severities: critical > serious > moderate > mild.

Document structure

Severity	Rule	Details
serious	<html> must have a valid lang attribute	e.g. lang="en". Check the value is a valid BCP 47 language tag. lang="und" (undetermined) is valid and not a failure — but recommend setting a specific language for better screen reader pronunciation.
serious	Body content wrappers must have lang and dir	Email clients often strip <html>, so direct children of <body> (excluding empty elements, <style>, <script>, and <img alt="">) need their own lang and dir attributes. If lang and dir are present but set to generic values (lang="und", dir="auto"), do not flag as a failure — instead note as a recommendation (mild) to set specific values for better assistive technology support.
serious	dir must be ltr, rtl, or auto	Flag any other value. dir="auto" is valid — recommend setting an explicit direction only as a mild improvement.
serious	Document should have a <title> element if the email has a view in browser link	Title is used for navigation on hosted version of the email.
critical	<meta name="viewport"> must not disable zoom	Flag maximum-scale=1, user-scalable=no, or user-scalable=0.