HTML Email Rendering Broken Across Email Clients
HTML emails generated by your Cursor-built application look great in the preview or in one email client, but are completely broken in others. Layouts collapse in Gmail, images don't load in Outlook, fonts revert to defaults in Yahoo Mail, and dark mode inverts your carefully chosen colors.
HTML email rendering is stuck in 1999 — email clients use wildly different HTML/CSS engines. Outlook uses Microsoft Word's HTML renderer, Gmail strips most CSS, and Apple Mail has its own quirks. Cursor generates modern HTML/CSS that works perfectly in browsers but violates almost every constraint of email client rendering.
The issue affects your brand perception and functionality. Broken emails look unprofessional, can obscure important content like verification links, and may even trigger spam filters that look for malformed HTML.
Error Messages You Might See
Common Causes
- External CSS stylesheets — Cursor linked to an external CSS file or used
<style>blocks in the head, which Gmail and many clients completely strip - Modern CSS properties — Flexbox, Grid, CSS variables, and media queries are unsupported in most email clients, especially Outlook
- Div-based layout — Cursor generated div-based layouts instead of table-based layouts, which are the only reliable layout method for email
- Images without alt text or dimensions — Images block loading by default in many clients. Without explicit width/height attributes, layouts break when images are hidden
- Web fonts and custom fonts — Custom font imports are ignored by most email clients, causing text to render in fallback system fonts with different sizing
- Dark mode not handled — Email clients' dark mode inverts colors unpredictably, making light text on light backgrounds or dark text on dark backgrounds
How to Fix It
- Use inline CSS only — Move all styles to inline style attributes on each HTML element. Use a CSS inliner tool like juice or Premailer to automate this conversion
- Use table-based layouts — Replace all div layouts with nested
<table>elements. Userole="presentation"for accessibility. This is the only reliable cross-client layout method - Use a tested email framework — Replace Cursor's custom HTML with a battle-tested email framework like MJML, React Email, or Maizzle that compiles to compatible HTML
- Add explicit image dimensions — Always include width and height attributes on img tags, and add alt text so content makes sense when images are blocked
- Test across email clients — Use Litmus or Email on Acid to preview your emails in 90+ email clients before sending
- Handle dark mode explicitly — Add
@media (prefers-color-scheme: dark)styles and use thecolor-schememeta tag. Provide both light and dark versions of logos
Real developers can help you.
Meïr Ankri
Full-stack developer specializing in React / Next.js / Node.js with 6+ years of experience. I've worked across various sectors including automotive (Reezocar/Société Générale), healthcare (Medical Link SaaS), and e-commerce (Glasman). I build web apps end-to-end, from architecture to production, with a focus on scalability, performance, and code quality. I also mentor junior developers and contribute to technical decisions and code reviews.
Matthew Jordan
I've been working at a large software company named Kainos for 2 years, and mainly specialise in Platform Engineering. I regularly enjoy working on software products outside of work, and I'm a huge fan of game development using Unity. I personally enjoy Python & C# in my spare time, but I also specialise in multiple different platform-related technologies from my day job.
Costea Adrian
Embedded Engineer specilizing in perception systems. Latest project was a adas camera calibration system.
Jaime Orts-Caroff
I'm a Senior Android developer, open to work in various fields
legrab
I'll fill this later
Sage Fulcher
Hey I'm Sage! Im a Boston area software engineer who grew up in South Florida. Ive worked at a ton of cool places like a telehealth kidney care startup that took part in a billion dollar merger (Cricket health/Interwell health), a boutique design agency where I got to work on a ton of exciting startups including a photography education app, a collegiate Esports league and more (Philosophie), a data analytics as a service startup in Cambridge (MA) as well as at Phillips and MIT Lincoln Lab where I designed and developed novel network security visualizations and analytics. I've been writing code and furiously devoted to using computers to make people’s lives easier for about 17 years. My degree is in making computers make pretty lights and sounds. Outside of work I love hip hop, the Celtics, professional wrestling, magic the gathering, photography, drumming, and guitars (both making and playing them)
Jen Jacobsen
I’m a Full-Stack Developer with over 10 years of experience building modern web and mobile applications. I enjoy working across the full product lifecycle — turning ideas into real, well-built products that are intuitive for users and scalable for businesses.
I particularly enjoy building mobile apps, modern web platforms, and solving complex technical problems in a way that keeps systems clean, reliable, and easy to maintain.
Victor Denisov
Developer
Anthony Akpan
Developer with 8 years of experience building softwares fro startups
Basel Issmail
’m a Senior Full-Stack Developer and Tech Lead with experience designing and building scalable web platforms. I work across the full development lifecycle, from translating business requirements into technical architecture to delivering reliable production systems.
My work focuses on modern web technologies, including TypeScript, Angular, Node.js, and cloud-based architectures. I enjoy solving complex technical problems and helping teams turn product ideas and prototypes into working platforms that can grow and scale.
In addition to development, I often collaborate closely with product managers, business analysts, designers, and QA teams to ensure that solutions align with both technical and business goals.
I enjoy working with startups and product teams where I can contribute both as a hands-on engineer and as a technical partner in designing and delivering impactful software.
You don't need to be technical. Just describe what's wrong and a verified developer will handle the rest.
Get HelpFrequently Asked Questions
Why can't I use modern CSS in emails?
Email clients use different rendering engines than browsers. Outlook uses Microsoft Word's HTML renderer (which barely supports CSS2), Gmail strips all CSS from the head and only keeps inline styles, and each client has its own quirks. Stick to inline CSS, table layouts, and basic CSS properties.
What is the best way to create HTML emails?
Use a purpose-built email framework: MJML (markup language that compiles to compatible HTML), React Email (for React developers), or Maizzle (Tailwind CSS for emails). These frameworks handle cross-client compatibility so you don't have to.