HTML email accessibility: what to code, and what each client keeps

A skeleton that passes the basics

Before the details, here is the smallest email that satisfies the language, table, heading and reading-order points in one piece. The hidden preheader sits first, the layout tables carry role="presentation", and the heading is a real h1 styled inline because email clients ignore the browser's default heading look only some of the time.

<!DOCTYPE html>
<html lang="en" dir="ltr" xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Your invoice for September is ready</title>
</head>
<body lang="en" dir="ltr" style="margin:0; padding:0;">
  <div style="display:none; max-height:0; overflow:hidden;">Invoice 4812 is attached and due on October 21.</div>
  <table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0">
    <tr>
      <td align="center">
        <table role="presentation" width="600" style="max-width:600px;" cellspacing="0" cellpadding="0" border="0">
          <tr>
            <td style="padding:24px; font-family:Arial, Helvetica, sans-serif; font-size:16px; line-height:24px; color:#333333;">
              <h1 style="margin:0 0 16px 0; font-size:24px; line-height:30px;">Your September invoice</h1>
              <p style="margin:0 0 16px 0;">Invoice 4812 is ready. The amount of $240.00 is due on October 21.</p>
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
</body>
</html>

Each choice has a source. W3C's guidance on declaring language in HTML says to put the language on the html element rather than body, because body does not cover the head. Email adds a wrinkle: some clients strip the html and body wrappers when they embed the message in their own page, which is why React Email's documentation tells you to repeat the same lang and dir on the body component. Doing it on both costs two attributes.

Declare the language, and mark the exceptions

WCAG 3.1.1 (Language of Page, Level A) exists so that screen readers can load the correct pronunciation rules; the Understanding document says visual browsers also use it to display characters correctly. Criterion 3.1.2 (Language of Parts, Level AA) covers passages in another language:

<p>Your order ships with a <span lang="fr">carte cadeau</span> for the winter sale.</p>

The caniemail entry for lang shows support in Gmail, Apple Mail and Outlook, and a partial result in Yahoo and AOL, where the note says it is not supported on td elements. The practical rule is to attach lang to html, body, p or span, never to the cell that carries your layout. For right-to-left languages, the dir entry lists support in Gmail and Apple Mail, a partial result in Outlook for Windows (buggy on anchor tags), and a Gmail mobile-webmail bug where the client applies rtl to the entire email if any text in it is right-to-left.

Layout tables versus data tables

Email layouts are tables because layout CSS such as flexbox and grid is unavailable in Outlook for Windows, and caniemail's table entry shows the element supported in every client it tracks. The cost is that a screen reader may announce rows and columns for a structure that has none. The fix is role="presentation", which the WAI-ARIA specification describes as an element whose implicit native role semantics will not be mapped to the accessibility API. The role entry on caniemail has two caveats worth reading: the Outlook for Windows result comes from inspecting processed code on Litmus rather than a live test, and Yahoo and AOL keep the attribute only on table.

When the table is the content, do the opposite. W3C's Tables tutorial says header cells must be marked up with th and data cells with td, with scope to define the direction of each header when it is not obvious, and a caption to name the table's topic. An invoice line-item grid, a usage report or a plan comparison belongs in that form:

<table width="100%" cellspacing="0" cellpadding="8" border="0" style="border-collapse:collapse;">
  <caption style="text-align:left; padding:0 0 8px 0;">Usage in September</caption>
  <tr>
    <th scope="col" align="left">Plan</th>
    <th scope="col" align="right">Seats</th>
    <th scope="col" align="right">Amount</th>
  </tr>
  <tr>
    <th scope="row" align="left">Team</th>
    <td align="right">6</td>
    <td align="right">$240.00</td>
  </tr>
</table>

Keep data tables small. A wide grid has to survive a 320 pixel viewport (WCAG 1.4.10 Reflow asks for content without two-dimensional scrolling at that width, except where two-dimensional layout is needed for meaning), and if it cannot, link to a web page that carries the table.

Headings, lists and the elements that do not make it

W3C's headings tutorial says to nest headings by rank and warns that skipping ranks, an h2 followed directly by an h4, can be confusing. The caniemail entry for h1 to h6 shows support across every client it lists, so a heading is the one piece of structure with no caveats. Style it inline (size, weight, margin) and use the rank for meaning, not for size.

HTML5 sectioning is a different story. The semantics entry reports Outlook for Windows as unsupported, Yahoo as unsupported with the tags stripped, and Gmail as partial: main, nav, details and summary are not supported and their tags are replaced by u. Landmarks therefore cannot be your navigation aid in email, and the headings have to do that work. Lists are fine with one caveat: the lists entry marks reversed on ol as unsupported in Gmail and Outlook, which only matters if you count backwards.

Reading order is source order

WCAG 1.3.2 (Meaningful Sequence) says that when the order of content affects meaning, a correct reading sequence must be programmatically determinable. In a table layout the programmatic order is the order of cells in the markup, not the order your eye follows. A two-column product row therefore reads the whole left cell before the right one, and a layout that reverses columns on mobile with dir="rtl" tricks or display tricks reads in source order whatever the screen shows. Write the source in the order a person should hear it: headline, summary, action, then supporting detail, and let the columns stack in that same sequence on small screens. Info and Relationships (1.3.1) is the companion rule: if bold text is acting as a heading or a row of dashes is acting as a list, mark it up as one.

Images: four jobs, four alts

WCAG 1.1.1 (Non-text Content) requires a text alternative that serves the equivalent purpose, and says purely decorative content should be implemented so assistive technology can ignore it. W3C's image tutorials turn that into four jobs, and an email has all of them:

<!-- Informative: say what the picture adds -->
<img src="https://example.com/img/chart-sept.png" width="560" alt="Bar chart: usage grew from 410 to 520 seats between August and September" style="display:block; width:100%; max-width:560px; height:auto;">

<!-- Decorative: empty alt, never omitted -->
<img src="https://example.com/img/divider.png" width="560" height="4" alt="" style="display:block;">

<!-- Functional: describe the action, not the picture -->
<a href="https://example.com/invoices/4812">
  <img src="https://example.com/img/download-pdf.png" width="180" alt="Download invoice 4812 as PDF" style="display:block;">
</a>

<!-- Logo inside a link that already has text: empty alt avoids saying it twice -->
<a href="https://example.com/">
  <img src="https://example.com/img/logo.png" width="120" alt="" style="vertical-align:middle;">
  Acme billing home
</a>

The decorative images page says to provide a null alt, and adds that leaving the attribute out is not an option, because some screen readers then announce the file name. The functional images page says the alternative should convey the action rather than describe the picture, so "print this page" rather than "printer". There is no character limit in either document. Images are also the part of an email most likely to be blocked, which gives alt text a second job: with images off, the alt is what remains. Style it with a font size and colour on the img so a blocked image shows a legible line of text, and never place the only copy of a date, code or price inside an image. Images of Text (1.4.5) says to use text rather than images of text where the technology allows, with logotypes as the exception.

Links and buttons

WCAG 2.4.4 (Link Purpose in Context) says the purpose of each link can be determined from the link text alone or with its programmatic context, except where the purpose would be ambiguous to everyone. A newsletter with five "Read more" links fails in a screen reader's links list; five links that name the article pass. In email, a button is an anchor styled as a button, and React Email's documentation says as much: quite often in the email world people say buttons when they mean links.

<table role="presentation" cellspacing="0" cellpadding="0" border="0">
  <tr>
    <td bgcolor="#0a58ca" style="background-color:#0a58ca; border-radius:4px;">
      <a href="https://example.com/invoices/4812"
         style="display:inline-block; padding:14px 28px; min-height:24px; font-family:Arial, Helvetica, sans-serif; font-size:16px; line-height:20px; font-weight:bold; color:#ffffff; text-decoration:none;">
        Pay invoice 4812
      </a>
    </td>
  </tr>
</table>

Two details in that sample come from standards. The padding makes the target comfortably larger than the 24 by 24 CSS pixel minimum in WCAG 2.2's new Target Size (Minimum) criterion (2.5.8, Level AA); a text link inside a sentence is exempt through the inline exception, but a row of small icon links is not. And the colour pair is chosen for contrast: white on #0a58ca is 6.44:1, whereas white on the #007bff blue many templates use is 3.98:1, below the 4.5:1 that normal-size text needs.

Contrast, size and spacing

WCAG 1.4.3 (Contrast (Minimum), Level AA) asks for at least 4.5:1 for text, and 3:1 for large-scale text. The Understanding page defines large as 18 point, or 14 point bold, and converts them: about 24 px and about 18.5 px. A lot of email advice says 18 px, which is wrong by a wide margin. Logotypes and pure decoration have no requirement. Some pairs worth knowing, computed with the WCAG relative-luminance formula:

The orange row is not hypothetical: it is the button colour in the example on the MJML documentation page for mj-button, a reminder to check sample code before you paste it.

Controls and meaningful graphics have their own floor: Non-text Contrast (1.4.11) asks for 3:1 against adjacent colours for user interface components and graphical objects needed to understand content, which is why a pale-grey outline button on white fails even when its label passes. Use of Color (1.4.1) says colour must not be the only visual means of conveying information, so a red price needs the word "overdue" or an icon with text beside it.

Size and spacing sit under Text Spacing (1.4.12), which requires that nothing is lost when a reader sets line height to at least 1.5 times the font size, paragraph spacing to 2 times, letter spacing to 0.12 times and word spacing to 0.16 times. In email, that means avoiding fixed-height cells and tight line-height on text blocks that carry content. Use px for font-size: the font-size entry shows rem unsupported in Outlook for Windows, Yahoo, AOL and the GMX family.

Focus, motion and what to skip

Keyboard users depend on a visible focus indicator, and email is a poor place to restyle it. The :focus entry shows no support in Gmail and Outlook for Windows, and the outline entry shows Gmail supporting it while Outlook for Windows does not. The sensible position is to leave the client's default focus ring alone, which is the opposite of the advice to add outline to every link. For motion, prefers-reduced-motion works in Apple Mail and Outlook.com but not in Gmail, so animated GIFs and CSS animation need a safe still frame as the first frame, and nothing should flash.

What the authoring tools do for you, per their own documentation

Accessibility claims in tool marketing are easy to find and hard to verify, so this section lists only what the documentation I read states. MJML takes lang and dir on the root mjml tag and writes them to the html tag and a wrapping div inside the body; the docs add that MJML puts role="article", aria-roledescription="email" and an aria-label taken from mj-title on that div. Its mj-table accepts role with none or presentation, and mj-image has an alt attribute that defaults to an empty string, so a forgotten alt silently becomes a decorative image. React Email's Html component takes lang (default en) and dir (default ltr), its Img component lists an alt prop, and its render utility can produce a plain-text version, which the docs call important because some recipients disable HTML email for security or accessibility reasons. The same source in both frameworks looks like this:

<mjml lang="en" dir="ltr">
  <mj-head>
    <mj-title>Your September invoice</mj-title>
    <mj-preview>Invoice 4812 is due on October 21.</mj-preview>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-image src="https://example.com/img/logo.png" width="120px" alt="Acme billing" />
        <mj-text font-size="16px" color="#333333">Invoice 4812 is ready.</mj-text>
        <mj-button href="https://example.com/invoices/4812" background-color="#0a58ca" color="#ffffff">
          Pay invoice 4812
        </mj-button>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

import { Html, Body, Container, Heading, Text, Button, Img, Preview } from "react-email";

export default function Invoice() {
  return (
    <Html lang="en" dir="ltr">
      <Preview>Invoice 4812 is due on October 21.</Preview>
      <Body lang="en" dir="ltr">
        <Container>
          <Img src="https://example.com/img/logo.png" alt="Acme billing" width="120" />
          <Heading as="h1">Your September invoice</Heading>
          <Text>Invoice 4812 is ready.</Text>
          <Button href="https://example.com/invoices/4812">Pay invoice 4812</Button>
        </Container>
      </Body>
    </Html>
  );
}

Both samples follow the documentation pages for MJML and for React Email's Html, Image and render. Neither framework checks your contrast or your link text, and neither can know that an alt is wrong. If you are choosing between them for other reasons, MJML vs React Email covers the rest. Visual builders and testing platforms each publish their own accessibility claims; read them on the vendor's pages and export one real template to inspect the output, as the HTML email builder guide suggests, rather than trusting a feature list.

A release check that fits in ten minutes

Run these against the compiled HTML, not the builder canvas, and write down the client and assistive technology for any exception.

For the CSS side of these checks, see the CSS in email guide and the client compatibility guide; for the colour-mode side, the dark mode guide.