Setting the file. One moment.
Skill 02 · Email Best Practices
Subchapter 2.1
references/accessibility.mdMarkdown9 KBView on GitHub
Emails must be readable by screen readers, dark-mode clients, translation tools, and AI agents — not just sighted readers on a default inbox. The rules below are mechanical. Apply them every time.
Both attributes are needed in two places: on <html> and on the direct children of <body>. Several email clients strip the attributes from <html>, which is why duplicating them on the body’s children is the single most common accessibility failure in production email.
<html lang="en" dir="ltr">
<head>
<title>Your weekly product updates</title>
</head>
<body>
<div lang="en" dir="ltr">
<!-- email content -->
</div>
</body>
</html>lang: a BCP 47 language tag (opens in a new tab) (en, pt-BR, ja, ar)dir: ltr, rtl, or autoFallbacks when the correct values aren’t available (use only when you genuinely don’t know):
dir="auto" — lets the user agent infer direction from contentlang="und" — marks the language as undeterminedBoth fallbacks are worse than the correct value but much better than nothing. For multi-locale templates, pass the locale through; do not hardcode en.
Any <table> used for layout must have role="presentation" (or the equivalent role="none"). Otherwise screen readers announce “table, row 1 of N” for every layout row and the email becomes unusable. Prefer avoiding layout tables entirely; when you can’t, mark them.
<table role="presentation" cellpadding="0" cellspacing="0" border="0">
<tr>
<td>...</td>
</tr>
</table>Leave a <table> without role="presentation" only when the data is genuinely tabular (line items, comparison rows). Tabular data should also use <th scope="col"> for column headers.
Most emails should have one <h1> that names the email, with subheadings nested in order:<h1> → <h2> → <h3>. Never skip levels. Never fake a heading with bold <p>.
<h1>Order confirmation</h1>
<h2>Items</h2>
<h2>Shipping</h2>
<h3>Address</h3>
<h3>Tracking</h3>Headings are how assistive tech and AI clients navigate and summarize the email.
Exception: very short messages (SMS-style notifications, single-sentence alerts) may not need a heading at all. If the email body is one or two sentences, skip the <h1> rather than wrap a heading around the only content.
Every <a> must contain text content that a screen reader can announce. The most common failure is a linked image with no alt text.
A linked image is never decorative. It’s functional, so its alt must describe what clicking does, not just what the image looks like.
<!-- Wrong: linked image with no accessible name -->
<a href="/order/123">
<img src="view-order.png" alt="">
</a>
<!-- Right: alt describes the action -->
<a href="/order/123">
<img src="view-order.png" alt="View order #123">
</a>
<!-- Also right: visible text alongside the image -->
<a href="/order/123">
<img src="icon.png" alt="">
View order #123
</a>When the visible link text can’t carry enough information, add visually hidden text inside the <a> (see goodemailcode.com/email-accessibility/visually-hidden-text (opens in a new tab)). aria-label and title on <a> have limited support in email clients. Prefer real text content or visually hidden text.
Even when a link has text, it must describe where the link goes. Never use “click here,” “learn more,” “read more,” or bare URLs. Screen reader users often navigate by jumping between link texts with no surrounding context.
<!-- Wrong -->
<a href="...">click here</a>
<a href="...">https://resend.com/blog/...</a>
<!-- Right -->
<a href="...">Read the 2026 accessibility report</a>Two distinct rules, both mandatory. alt must always be present; the value depends on the image’s role.
Meaningful images (product shots, charts, screenshots, anything carrying information): describe purpose and key details in context.
<!-- Wrong: redundant, vague -->
<img src="..." alt="image">
<img src="..." alt="photo of a bike">
<!-- Right: purpose + key details -->
<img src="..." alt="Red bicycle leaning against a brick wall on a rainy street">Decorative images (spacers, dividers, background flourishes, pure branding ornaments): use an empty alt="". This tells screen readers to skip them. Never omit the attribute entirely — omitting it and alt="" are not equivalent; some screen readers announce the filename when alt is absent.
<img src="divider.png" alt="" role="presentation">If an image conveys no information that isn’t already in the surrounding text, it is decorative. If it’s inside an <a>, it is not decorative — see the “Every link must have discernible text” rule.
Many clients and assistive technologies read <title> before anything else. It’s also shown when the email is viewed as a web page. Treat it like the subject line, not the brand name.
<head>
<title>Your weekly product updates from Resend</title>
</head>If the per-email title is hard to populate, a generic but specific fallback like "Email from {Brand Name}" still beats nothing.
Verify with the WebAIM Contrast Checker (opens in a new tab) or browser devtools.
Dark mode. Outlook, Apple Mail, and others force dark mode and derive dark colors from your light ones. Healthy starting contrast keeps the auto-inverted version readable. Always preview in dark mode before shipping.
When you can’t fix everything, fix in this order:
alt on imageslang/dir (on <html> and body children), role="presentation" on layout tables, links without discernible text, missing <title>, color contrast<h1> (skip the fix for very short messages)Run this on every template:
<html> has lang and dir; direct children of <body> also have lang and dir<title> set on <head>, specific to this email (not the brand name)<table> elements have role="presentation" (or role="none")<h1> (or none, for very short messages); <h2>/<h3> nested in order<a> has discernible text — visible text, descriptive alt on linked images, or visually hidden textalt; every decorative image has an explicit alt=""alt="" (linked images are functional, never decorative)Cmd+F5) or NVDA on Windows. Listen top to bottom; if anything is confusing, fix the markup.Automated tests do not catch everything. They will not tell you whether alt text actually matches the image, whether headings make semantic sense, or whether text inside an image is readable on narrow viewports. Even the three brands that passed every automated check in the EMC 2026 report had judgment-level issues like generic alt text on decorative images, alt text that didn’t match the image, and 10px footer text. Treat automation as a floor, not a ceiling.
When generating templates with React Email, the latest version handles several of the structural rules: <Html> sets lang/dir, <Img> defaults to alt="", <Markdown> tables render role="presentation", and <Preview> emits a <title>. Upgrade with npm install react-email@latest. The content rules — heading hierarchy, descriptive alt and link text, contrast, the linked-image rule — still have to be applied by hand.