Email Development: HTML Emails That Work Everywhere

Introduction

Email remains one of the most critical channels for digital communication, yet HTML email development is notoriously challenging. Unlike web browsers, email clients have fragmented support for HTML, CSS, and modern web standards. Outlook, Gmail, Apple Mail, and others render emails differently, creating a frustrating experience for developers. This guide provides practical solutions for building robust HTML emails that work across all major platforms.

Problem 1: CSS Support Fragmentation

The Problem: Email clients strip out <style> tags, don't support external stylesheets, and have limited CSS property support. Outlook uses Word's rendering engine, Gmail removes <head> sections entirely, and mobile clients have unpredictable behavior.

The Solution: Use inline CSS exclusively. Inline styles are universally supported and survive email client processing. For complex layouts, use HTML tables as the foundation, which all clients render consistently.

Code:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Welcome Email</title>
</head>
<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
    <table width="100%" border="0" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4;">
        <tr>
            <td align="center" style="padding: 20px;">
                <table width="600" border="0" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px;">
                    <!-- Header -->
                    <tr>
                        <td style="padding: 30px; background-color: #2c3e50; text-align: center;">
                            <h1 style="margin: 0; color: #ffffff; font-size: 28px; font-weight: bold;">Welcome!</h1>
                        </td>
                    </tr>

                    <!-- Content -->
                    <tr>
                        <td style="padding: 30px; color: #333333; font-size: 16px; line-height: 1.6;">
                            <p style="margin: 0 0 15px 0;">Hi there,</p>
                            <p style="margin: 0 0 15px 0;">Thank you for joining us. We're excited to have you on board.</p>
                            <p style="margin: 0;">Best regards,<br>The Team</p>
                        </td>
                    </tr>

                    <!-- CTA Button -->
                    <tr>
                        <td style="padding: 0 30px 30px 30px; text-align: center;">
                            <a href="https://example.com/activate" style="display: inline-block; padding: 12px 30px; background-color: #3498db; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold;">Get Started</a>
                        </td>
                    </tr>

                    <!-- Footer -->
                    <tr>
                        <td style="padding: 20px; background-color: #ecf0f1; text-align: center; font-size: 12px; color: #7f8c8d; border-top: 1px solid #bdc3c7;">
                            <p style="margin: 0;">© 2024 Your Company. All rights reserved.</p>
                            <p style="margin: 5px 0 0 0;">
                                <a href="#" style="color: #3498db; text-decoration: none;">Unsubscribe</a> | 
                                <a href="#" style="color: #3498db; text-decoration: none;">Preferences</a>
                            </p>
                        </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</body>
</html>

Tips:

Always reset default margins and padding on elements
Use line-height for better readability
Set explicit widths on tables (600px is standard for desktop)
Use align="center" on table cells for Outlook compatibility

Problem 2: Outlook Rendering Issues

The Problem: Outlook 2007-2019 uses Microsoft Word's rendering engine, which doesn't support many CSS properties like border-radius, box-shadow, background-size, or media queries. It also has issues with padding on table cells and doesn't recognize max-width.

The Solution: Use conditional comments to target Outlook specifically. Create Outlook-safe versions of complex designs using VML (Vector Markup Language) for rounded corners and gradients.

Code:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Outlook-Safe Email</title>
    <!--[if gte mso 9]>
        <style>
            table { border-collapse: collapse; }
        </style>
    <![endif]-->
</head>
<body style="margin: 0; padding: 0;">
    <table width="100%" border="0" cellpadding="0" cellspacing="0">
        <tr>
            <td align="center">
                <table width="600" border="0" cellpadding="0" cellspacing="0" style="background-color: #ffffff;">
                    <!-- Rounded corner box using VML for Outlook -->
                    <tr>
                        <td style="padding: 20px;">
                            <!--[if gte mso 9]>
                                <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="https://example.com" style="height:40px;v-text-anchor:middle;width:200px;" arcsize="50%" stroke="f" fillcolor="#3498db">
                                    <w:anchorlock/>
                                    <center style="color:#ffffff;font-family:Arial;font-size:14px;font-weight:bold;">Click Here</center>
                                </v:roundrect>
                            <![endif]-->
                            <!--[if !gte mso 9]><!-->
                                <a href="https://example.com" style="display: inline-block; padding: 10px 20px; background-color: #3498db; color: #ffffff; text-decoration: none; border-radius: 20px; font-weight: bold;">Click Here</a>
                            <!--<![endif]-->
                        </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</body>
</html>

Tips:

Use <!--[if gte mso 9]> to target Outlook 2007 and later
Use  to hide Outlook-specific code from other clients
Always provide fallbacks for non-Outlook clients
Test in Outlook 2007, 2010, 2013, 2016, and 2019

Problem 3: Gmail and Mobile Responsiveness

The Problem: Gmail strips out <style> tags and media queries entirely. Mobile clients need responsive designs, but Gmail doesn't support media queries. Additionally, Gmail removes the <head> section, so any styles defined there are lost.

The Solution: Use mobile-first inline styles combined with media queries for clients that support them. Use max-width with fallback widths. For Gmail, design a single-column layout that works on all screen sizes.

Code:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Responsive Email</title>
    <style>
        @media only screen and (max-width: 600px) {
            table[class="responsive-table"] {
                width: 100% !important;
            }
            td[class="responsive-cell"] {
                width: 100% !important;
                display: block !important;
                padding: 15px !important;
            }
            img[class="responsive-img"] {
                width: 100% !important;
                height: auto !important;
            }
            .hide-mobile {
                display: none !important;
            }
        }
    </style>
</head>
<body style="margin: 0; padding: 0; background-color: #f4f4f4;">
    <table width="100%" border="0" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4;">
        <tr>
            <td align="center" style="padding: 10px;">
                <table width="600" border="0" cellpadding="0" cellspacing="0" class="responsive-table" style="background-color: #ffffff; max-width: 600px;">
                    <!-- Hero Image -->
                    <tr>
                        <td style="padding: 0;">
                            <img src="https://example.com/hero.jpg" alt="Hero" class="responsive-img" style="width: 600px; height: auto; display: block; border: 0;">
                        </td>
                    </tr>

                    <!-- Two Column Section (Desktop) / Single Column (Mobile) -->
                    <tr>
                        <td style="padding: 20px;">
                            <table width="100%" border="0" cellpadding="0" cellspacing="0">
                                <tr>
                                    <td class="responsive-cell" style="width: 48%; padding: 10px; vertical-align: top;">
                                        <h3 style="margin: 0 0 10px 0; color: #2c3e50; font-size: 18px;">Feature 1</h3>
                                        <p style="margin: 0; color: #555555; font-size: 14px; line-height: 1.5;">Description of feature one goes here.</p>
                                    </td>
                                    <td class="responsive-cell" style="width: 48%; padding: 10px; vertical-align: top;">
                                        <h3 style="margin: 0 0 10px 0; color: #2c3e50; font-size: 18px;">Feature 2</h3>
                                        <p style="margin: 0; color: #555555; font-size: 14px; line-height: 1.5;">Description of feature two goes here.</p>
                                    </td>
                                </tr>
                            </table>
                        </td>
                    </tr>

                    <!-- Mobile-Only Content -->
                    <tr>
                        <td style="padding: 20px; text-align: center; background-color: #ecf0f1;">
                            <p style="margin: 0; color: #7f8c8d; font-size: 12px;">Viewing on mobile? <a href="https://example.com" style="color: #3498db; text-decoration: none;">View full version</a></p>
                        </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</body>
</html>

Tips:

Use max-width with explicit width fallback
Design for 600px width (standard email width)
Use !important in media queries to override inline styles
Test on Gmail, Gmail mobile app, and other mobile clients
Use display: block on table cells in mobile view

Problem 4: Image Handling and Alt Text

The Problem: Many email clients block images by default. Users see broken image icons or blank spaces. Additionally, images can break layouts if not properly constrained, and responsive images are difficult to implement.

The Solution: Always include descriptive alt text. Use background colors and text as fallbacks. Constrain image dimensions and use display: block to prevent spacing issues.

Code:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Image-Safe Email</title>
</head>
<body style="margin: 0; padding: 0;">
    <table width="100%" border="0" cellpadding="0" cellspacing="0">
        <tr>
            <td align="center">
                <table width="600" border="0" cellpadding="0" cellspacing="0" style="background-color: #ffffff;">
                    <!-- Image with fallback background -->
                    <tr>
                        <td style="background-color: #3498db; background-image: url('https://example.com/bg.jpg'); background-size: cover; padding: 40px 20px; text-align: center;">
                            <img src="https://example.com/logo.png" alt="Company Logo" style="width: 200px; height: auto; display: block; margin: 0 auto; border: 0;">
                        </td>
                    </tr>

                    <!-- Product Image with Text Fallback -->
                    <tr>
                        <td style="padding: 20px; text-align: center;">
                            <img src="https://example.com/product.jpg" alt="Premium Product - Blue Widget with advanced features" style="width: 100%; max-width: 500px; height: auto; display: block; border: 1px solid #ddd; border-radius: 4px;">
                        </td>
                    </tr>

                    <!-- Text-based content for image-blocked clients -->
                    <tr>
                        <td style="padding: 20px; background-color: #f9f9f9; text-align: center; font-size: 14px; color: #666;">
                            <p style="margin: 0;">
                                <strong>Images not displaying?</strong><br>
                                <a href="https://example.com/view-online" style="color: #3498db; text-decoration: none;">View this email in your browser</a>
                            </p>
                        </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</body>
</html>

Tips:

Always use descriptive alt text (not just "image")
Set display: block on images to remove bottom spacing
Use max-width: 100% for responsive images
Include border: 0 to remove default image borders
Provide text-based fallback content
Use background colors that match image content

Problem 5: Font and Typography Issues

The Problem: Email clients have limited font support. Web fonts don't work in most email clients. Font sizes render inconsistently, and line-height behaves unpredictably. Some clients don't support font weights properly.

The Solution: Use web-safe fonts as primary choices with fallbacks. Avoid web fonts unless using @font-face with proper fallbacks. Use explicit font sizes and line-heights. Use images for critical branding typography.

Code:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Typography Email</title>
    <style>
        @font-face {
            font-family: 'CustomFont';
            src: url('https://example.com/font.woff2') format('woff2'),
                 url('https://example.com/font.woff') format('woff');
            font-weight: normal;
            font-style: normal;
        }
    </style>
</head>
<body style="margin: 0; padding: 0; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 16px; line-height: 1.6; color: #333333;">
    <table width="100%" border="0" cellpadding="0" cellspacing="0">
        <tr>
            <td align="center">
                <table width="600" border="0" cellpadding="0" cellspacing="0" style="background-color: #ffffff;">
                    <!-- Heading with Image Fallback -->
                    <tr>
                        <td style="padding: 30px; text-align: center;">
                            <h1 style="margin: 0; font-family: Georgia, serif; font-size: 32px; font-weight: bold; line-height: 1.2; color: #2c3e50;">
                                Special Offer
                            </h1>
                        </td>
                    </tr>

                    <!-- Body Text -->
                    <tr>
                        <td style="padding: 0 30px 20px 30px;">
                            <p style="margin: 0 0 15px 0; font-family: Arial, sans-serif; font-size: 16px; line-height: 1.6; color: #555555;">
                                This is body text with proper line-height for readability.
                            </p>
                            <p style="margin: 0 0 15px 0; font-family: Arial, sans-serif; font-size: 16px; line-height: 1.6; color: #555555;">
                                <strong style="font-weight: bold; color: #2c3e50;">Bold text</strong> stands out clearly.
                            </p>
                        </td>
                    </tr>

                    <!-- List -->
                    <tr>
                        <td style="padding: 0 30px 30px 30px;">
                            <ul style="margin: 0; padding: 0 0 0 20px; font-family: Arial, sans-serif; font-size: 14px; line-height: 1.8; color: #555555;">
                                <li style="margin: 0 0 8px 0;">First benefit</li>
                                <li style="margin: 0 0 8px 0;">Second benefit</li>
                                <li style="margin: 0;">Third benefit</li>
                            </ul>
                        </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</body>
</html>

Web-Safe Font Stack:

font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
font-family: Georgia, 'Times New Roman', serif;
font-family: 'Courier New', monospace;

Tips:

Always include 3-4 font fallbacks
Use serif fonts for headlines, sans-serif for body
Set explicit font sizes (14-16px for body text)
Use line-height: 1.6 for better readability
Avoid web fonts unless absolutely necessary
Use images for critical branding fonts

Problem 6: Link and Button Styling

The Problem: Links render inconsistently across clients. Buttons created with CSS don't work in Outlook. Some clients add underlines or change colors unpredictably. Mobile clients may have touch-friendly requirements.

The Solution: Use inline styles for links. Create buttons using <a> tags with padding and background colors. Use display: inline-block for proper button rendering. Ensure sufficient touch target size (44x44px minimum).

Code:

```html <!DOCTYPE html>

Links and Buttons

Email Development: HTML Emails That Work Everywhere

Email Development: HTML Emails That Work Everywhere

Introduction

Problem 1: CSS Support Fragmentation

Problem 2: Outlook Rendering Issues

Problem 3: Gmail and Mobile Responsiveness

Problem 4: Image Handling and Alt Text

Problem 5: Font and Typography Issues

Problem 6: Link and Button Styling

Comments

More from this blog

Embedding-First Architecture for Real-World LLM Apps

AI/ML Modern Patterns

Containers/K8s Modern Patterns

Containers/K8s Modern Patterns

Containers/K8s Modern Patterns

Command Palette

Email Development: HTML Emails That Work Everywhere

Introduction

Problem 1: CSS Support Fragmentation

Problem 2: Outlook Rendering Issues

Problem 3: Gmail and Mobile Responsiveness

Problem 4: Image Handling and Alt Text

Problem 5: Font and Typography Issues

Problem 6: Link and Button Styling

Comments

More from this blog