MJML guide
A practical MJML email development checklist
MJML removes much of the table-layout work required by HTML email, but reliable delivery still depends on a disciplined build and QA process. Use this checklist before handing an email to marketing, lifecycle, or engineering teams.
1. Start with the message, not the layout
Before choosing sections or colors, identify the one action the reader should take. A promotional email might ask for a purchase, while a product update might ask a customer to explore a feature. That decision determines the hierarchy: headline first, supporting context second, and one primary call to action.
Keep the opening useful on its own. Subject lines and preheaders earn the open, but the first screen of the email should quickly answer what changed, why it matters, and what happens after the reader clicks. A clear content outline prevents an email from becoming a stack of equally weighted blocks.
2. Build with reusable sections
Treat each repeated pattern as a component: a hero, a feature row, a testimonial, a product card, and a footer. In MJML, that usually means keeping the structural elements—such as sections, columns, text, and buttons—simple and predictable. Reuse the same spacing, border, and type choices instead of tuning every block independently.
A consistent content width is especially important. Most marketing emails read well with a restrained central column, generous side padding on small screens, and short paragraphs. Avoid relying on advanced CSS features that email clients may strip or interpret differently. The compiler can create the required table markup, but it cannot turn an unstable visual system into a consistent email.
3. Make the call to action unambiguous
Give each email one primary button with a specific verb: “View the release notes,” “Start a trial,” or “Choose a plan.” Supporting links are fine, but they should not compete visually with the main action. The destination should also make sense when copied into plain text, because some clients or recipients may not load every visual treatment.
Check that a button has adequate contrast, enough padding to tap comfortably, and a complete destination URL. Placeholder links are useful during drafting but are easy to forget before send. Add this to your final preflight list rather than trusting a last-minute visual scan.
4. Design for narrow screens first
Email is frequently read on a phone, even when it is designed on a desktop. A two-column feature section may look balanced in a wide preview but feel cramped when stacked. Make sure headings do not become oversized, buttons remain easy to tap, and images communicate their purpose without tiny embedded text.
Images should have meaningful alternative text when they convey information. Decorative images can use an empty alternative description so a screen reader does not announce noise. For essential copy, use live text instead of baking it into an image; it improves accessibility, adapts to dark modes more gracefully, and still communicates when images are blocked.
5. Validate the source before sending
Compile your MJML and inspect both the source and the resulting HTML. Look for invalid nesting, missing attributes, unclosed tags, and copied fragments that do not belong in the current template. A structured validation pass is faster than debugging a broken campaign after it reaches a test inbox.
Next, review the content with a non-technical checklist: names and dates are correct, the unsubscribe and preference links are present where required, links point to the intended environment, and the sender name matches the campaign. This separates rendering correctness from campaign correctness; you need both.
6. Test the output in realistic inboxes
A browser preview is useful, but it is not an inbox test. Send the compiled HTML to a small seed list that includes at least one Gmail account, one Outlook account, and a mobile client your audience commonly uses. Check the subject line, preheader, dark-mode behavior, image loading, link tracking, and the layout above the fold.
Record recurring issues in your team’s template documentation. For example, if a particular Outlook client needs a simpler divider or a specific fallback font, solve it once in the reusable section rather than rediscovering it for every campaign. Reliable email production is a library and process problem as much as a one-off design problem.
Ready to build?
Use the MJML.ai workspace to create or repair a template, then follow this checklist before shipping the compiled result to your email platform.
Open MJML.ai