Email Marketing HTML Mjml

Email Marketing HTML and MJML

Create email that is beautiful, useful, truthful, reusable, accessible, compatible, measurable, and wanted. Visual impact never overrides recipient consent, transactional clarity, client compatibility, or sender reputation.

Mandatory workflow

1. Classify the message before writing

Classify it as:

• subscription marketing: newsletter, promotion, launch, discount, blog/update digest;
• cold outreach: individually relevant prospecting with jurisdiction and suppression controls;
• lifecycle: welcome, onboarding, nurture, activation, renewal, win-back;
• transactional: order, shipping, invoice, password/security, reservation, service status;
• hybrid: contains both transaction and promotion—separate it whenever possible.

Do not mix promotion into security, password-reset, receipt, or other essential transactional mail. The message class determines consent, unsubscribe, sender stream, markup, frequency, and copy.

2. Gather only material inputs

Infer from supplied brand/site files when available. Establish objective, audience/source of permission, brand rules, offer/evidence, message class, locale/jurisdictions, sender identity, desired action, personalization data, ESP/template engine, sending volume, and required output. Ask only for missing facts that would change compliance, truthfulness, or design.

Never invent prices, discounts, expiry dates, inventory, delivery dates, reviews, customer names, personalization, legal rights, or sender identity.

3. Build a message brief

Define one primary promise, one primary action, supporting evidence, objections, segmentation, subject/preheader angle, from/reply-to identity, fallback behavior, and success metric. Read references/01-strategy-and-brand.md and the relevant playbook in references/04-campaign-playbooks.md.

4. Write before decorating

Draft the subject, preview text, opening, body, CTA, proof, and footer in the approved brand voice. Keep the message skimmable and specific. Use references/02-copy-and-subject-lines.md.

5. Design the reusable system

Create design tokens for palette, typography/fallbacks, spacing, radii, dividers, background, buttons, image treatment, logo variants, and dark mode. Prefer a focused 600px single-column reading path; use columns only when they improve comprehension. Make the first screen valuable even with images blocked.

Use {{first_name}}, {{unsubscribe_url}}, and other documented placeholders only when data and fallback rules exist. Separate reusable layout, campaign content, and recipient data. Read references/03-personalization-and-automation.md.

Consider Emailcn when the target project uses React Email, @faire/mjml-react, or JSX Email and would benefit from locally owned registry components, blocks, themes, or font helpers. Read references/10-emailcn.md before recommending or installing it. Keep Emailcn optional: do not introduce a React renderer into a raw-MJML project merely to use its components, and do not run installation commands without user authorization.

6. Generate and compile the selected source

For raw MJML, read the required files in the Component Index, create a complete <mjml lang="..."> document with mj-title, mj-preview, attributes, accessibility metadata, and robust fallbacks, then follow compilation.md. For Emailcn, select exactly one renderer namespace, inspect every registry item before accepting it, adapt its local source to the approved brand system, and use that renderer's documented build process. In either path, deliver editable source and the final minified HTML; never assume a component preview proves inbox compatibility.

7. Add platform enhancements only when eligible

Use Gmail Promotions annotations only for genuine promotions with accurate live offers and assets. Use Gmail Actions/Highlights only for supported transactional cases and registered/eligible senders. Markup must match visible content and must degrade gracefully. Read references/07-google-email-annotations.md.

8. Run the deliverability and compliance gate

HTML cannot compensate for an unpermissioned list or unauthenticated domain. Verify list source, suppression, SPF, DKIM, DMARC alignment, TLS/PTR where applicable, sending stream, one-click and visible unsubscribe, sender identity, postal/contact details where required, frequency, volume ramp, and Postmaster/ESP feedback. Read references/05-deliverability-and-spam.md and references/06-compliance-and-list-governance.md.

9. Test the artifact and campaign

Validate MJML strictly, confirm includes landed, inspect compiled size, verify placeholders, links, tracking, alt text, contrast, dark mode, plain-text alternative, and rendering in representative clients. Send seed tests through the real infrastructure. Use references/08-testing-and-measurement.md.

Non-negotiable guardrails

• Do not send or authorize a campaign unless the user explicitly asks; creating a template is not permission to contact recipients.
• Do not purchase, scrape, harvest, guess, or enrich addresses for indiscriminate bulk sending.
• Do not use fake Re:/Fwd:, misleading display names, false urgency/scarcity, hidden content, deceptive links, or impersonation.
• Do not treat “spam words” as the main deliverability problem; permission, complaints, authentication, reputation, and engagement matter more.
• Do not hide unsubscribe or make it harder than subscribing.
• Do not put secrets, sensitive personal data, or private attributes into URLs, tracking parameters, annotations, or templates.
• Do not rely on open rate alone; privacy features and image proxying make it noisy.
• Do not promise inbox placement, Promotions-tab annotations, actions, or revenue.

Reusable output contract

For campaign work, provide as applicable:

1. campaign/message brief;
2. 3–5 truthful subject/preheader pairs with distinct hypotheses;
3. final copy and plain-text alternative;
4. editable source—raw MJML, React Email, MJML React, or JSX Email—and compiled HTML;
5. placeholder dictionary with type, example, required/optional state, escaping, and fallback;
6. sending-layer requirements: headers, authentication, unsubscribe, segmentation, suppression, and tracking;
7. QA results, known client limitations, and launch checklist;
8. measurement plan and one-variable test proposal.

Engineering rules

For raw MJML, retain the upstream rules: Section → Column → Content hierarchy; strict validation; component attributes for critical Gmail styles; font fallbacks; image alt text; heading roles via mj-html-attributes; VML-capable hero/section backgrounds; mj-group when columns must not stack; explicit include allowlists; minified HTML below Gmail clipping risk; and no JavaScript. For component renderers, apply the same output-level requirements after rendering. Registry components never waive accessibility, size, security, deliverability, compliance, or client-testing gates.

Component Index

Read only what the template needs:

Documentation and assets

Read references/INDEX.md for the complete reference index. Use assets/examples/reusable-mailing-list.mjml as the reusable personalization baseline and the upstream examples for specialized layout patterns. Use scripts/render_personalized_email.py only to preview/export personalized HTML; it deliberately does not send email.

Creator

This edition is maintained by Brownsmith Dynamics. Upstream authorship and licensing remain documented in references/09-sources-and-provenance.md and LICENSE.