Overview
The HTML Block feature in our Email Template Builder provides flexibility for custom content creation. However, to ensure optimal performance across our platform and email clients, it's crucial to follow these best practices. This guide focuses on CSS limitations, particularly the position property, and provides actionable guidelines for creating robust email templates.
CSS Position Property Guidelines
Never Use position: fixed
Why it's problematic:
position: fixedmakes elements relative to the viewport, not the email containerIt can overlay the entire CRM UI, making the system unusable
Email clients will strip or ignore this property anyway
Bad Example:
<!-- This will break the editor UI -->
<img
style="position:fixed;top:0;left:0;width:100vw;height:100vh;"
src="image.jpg"
alt=""
/>
<!-- This overlays everything -->
<div
style="position:fixed;top:0;left:0;width:100vw;height:100vh;
background:blue;z-index:9999;"
>
Content that breaks everything
</div>
Use position: relative Sparingly
When it can cause issues:
Offsets can break alignment with other template elements
May cause unexpected layout shifts in different email clients
Can interfere with the template's responsive behavior
Use with Caution:
<!-- May cause alignment issues -->
<div style="position:relative;top:10px;left:10px;">
This content is offset and may break layout consistency
</div>Acceptable Use:
<!-- Contained within a parent container -->
<div style="padding:30px;background:#fff5ec;border-radius:10px;">
<div
style="position:relative;top:5px;left:10px;
background:#ff6a00;color:white;padding:20px;
border-radius:8px;max-width:300px;"
>
Subtle highlight effect within container bounds
</div>
</div>
Avoid position: absolute
Similar issues to
position: fixedUnpredictable behavior across email clients
Can cause elements to overlap or disappear
Inline Styles and Responsiveness
The Responsiveness Challenge
Key Limitations:
Media queries are NOT supported in most email clients (especially Gmail)
Viewport units (
vw,vh) have limited supportFlexible layouts using CSS Grid or Flexbox are not reliable
What Won't Work:
<!-- Media queries will be stripped -->
<style>
@media (max-width: 600px) {
.responsive {
width: 100% !important;
}
}
</style>
<!-- Viewport units may not work -->
<div style="width:50vw;height:100vh;">Unreliable sizing</div>Better Approach:
<!-- Use percentage widths with max-width -->
<div style="width:100%;max-width:600px;margin:0 auto;">
<img style="width:100%;height:auto;" src="image.jpg" alt="" />
</div>
<!-- Use table-based layouts for consistency -->
<table style="width:100%;max-width:600px;margin:0 auto;">
<tr>
<td style="padding:20px;">Content that scales better</td>
</tr>
</table>Recommended Approaches
Use Table-Based Layouts
<table style="width:100%;border-collapse:collapse;">
<tr>
<td style="padding:20px;background:#f5f5f5;">
<table style="width:100%;max-width:600px;margin:0 auto;">
<tr>
<td style="padding:30px;background:white;border-radius:8px;">
Your content here
</td>
</tr>
</table>
</td>
</tr>
</table>
Container-Based Design
<!-- Outer wrapper -->
<div style="padding:20px;background:#f0f0f0;">
<!-- Inner container with max-width -->
<div
style="max-width:600px;margin:0 auto;background:white;
padding:30px;border-radius:10px;"
>
<!-- Content sections -->
<div style="margin-bottom:20px;">
<h2 style="color:#333;font-size:24px;margin:0 0 10px 0;">
Section Title
</h2>
<p style="color:#666;font-size:16px;line-height:1.5;margin:0;">
Your content goes here
</p>
</div>
</div>
</div>Mobile-Friendly Without Media Queries
<!-- Single column that works on all devices -->
<table style="width:100%;max-width:600px;margin:0 auto;">
<tr>
<td style="padding:20px;">
<!-- Fluid images -->
<img
style="width:100%;max-width:400px;height:auto;display:block;
margin:0 auto;"
src="image.jpg"
alt=""
/>
<!-- Readable text -->
<p style="font-size:16px;line-height:24px;color:#333;margin:20px 0;">
Text that remains readable on all devices
</p>
<!-- Touch-friendly buttons -->
<table style="margin:20px auto;">
<tr>
<td style="background:#ff6a00;border-radius:5px;">
<a
href="#"
style="display:block;padding:15px 30px;
color:white;text-decoration:none;
font-size:16px;font-weight:bold;"
>
Call to Action
</a>
</td>
</tr>
</table>
</td>
</tr>
</table>Code Examples
Good Example: Newsletter Header
<table style="width:100%;background:#fff5ec;">
<tr>
<td style="padding:40px 20px;">
<table style="width:100%;max-width:600px;margin:0 auto;">
<tr>
<td style="text-align:center;">
<img
style="width:150px;height:auto;"
src="logo.png"
alt="Company Logo"
/>
<h1
style="color:#ff6a00;font-size:28px;margin:20px 0 10px;
font-family:Arial,sans-serif;"
>
Welcome to Our Newsletter
</h1>
<p
style="color:#666;font-size:16px;margin:0;
font-family:Arial,sans-serif;"
>
Your weekly dose of insights and updates
</p>
</td>
</tr>
</table>
</td>
</tr>
</table>
Good Example: Content Block with Image
<table style="width:100%;max-width:600px;margin:0 auto;">
<tr>
<td style="padding:20px;">
<table style="width:100%;">
<tr>
<!-- Image column -->
<td style="width:200px;padding-right:20px;vertical-align:top;">
<img
style="width:100%;height:auto;border-radius:8px;"
src="feature.jpg"
alt="Feature"
/>
</td>
<!-- Text column -->
<td style="vertical-align:top;">
<h3 style="color:#333;font-size:20px;margin:0 0 10px;">
Feature Highlight
</h3>
<p style="color:#666;font-size:14px;line-height:1.5;margin:0;">
Description of your amazing feature that helps users accomplish
their goals more efficiently.
</p>
<a
href="#"
style="display:inline-block;margin-top:15px;
color:#ff6a00;text-decoration:none;
font-weight:bold;"
>
Learn More →
</a>
</td>
</tr>
</table>
</td>
</tr>
</table>Bad Example: What to Avoid
<!-- DON'T DO THIS -->
<div
style="position:fixed;top:0;left:0;width:100%;height:60px;
background:#333;z-index:1000;"
>
Fixed header that breaks everything
</div>
<div style="display:flex;justify-content:space-between;gap:20px;">
Flexbox won't work in most email clients
</div>
<div style="position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);">
Centered content that will likely disappear
</div>Troubleshooting
Help! I Added Problematic HTML and the UI is Broken!
If you've accidentally added HTML with styles that overlay or break the entire UI (like position: fixed), here's how to recover
Option 1: Quick Undo (Fastest)
If your cursor is still in the HTML textarea:
Press
Ctrl + Z(Windows/Linux) orCmd + Z(Mac) immediatelyThis will undo your last change and restore the previous HTML
Option 2: Start Fresh
If undo doesn't work or cursor is elsewhere:
Refresh the platform page
Create a new template
Your previous work will be lost, so this is a last resort
Prevention Tips
Test incrementally: Add HTML in small chunks and preview after each addition
Validate first: Test your HTML in a simple HTML file before pasting
Avoid risky CSS: Never use
position: fixed,position: absolute, or viewport unitsKeep backups: Save working HTML snippets externally before making major changes
Common UI-Breaking Patterns to Avoid
<!-- These will break the editor UI -->
<div style="position:fixed;top:0;left:0;width:100%;height:100%;">
<div style="position:absolute;z-index:99999;">
<div style="width:100vw;height:100vh;position:fixed;">
<img style="position:fixed;width:2000px;height:2000px;" />
</div>
</div>
</div>Quick Reference Checklist
DO:
Use inline styles only
Stick to table-based layouts for structure
Use percentage widths with max-width constraints
Test in multiple email clients
Keep designs simple and single-column for mobile
Use web-safe fonts with fallbacks
Provide alt text for all images
Use padding instead of margin where possible
Set explicit widths on table cells
Use
border-collapse: collapseon tablesTest HTML incrementally as you build
Keep cursor in textarea for easy undo
DON'T:
Use
position: fixedorposition: absoluteRely on CSS3 features (animations, transforms, etc.)
Use JavaScript or interactive elements
Include
<style>tags or external CSSUse media queries for responsiveness
Depend on Flexbox or CSS Grid
Use viewport units (vw, vh)
Include video or audio elements
Use CSS frameworks (Bootstrap, Tailwind, etc.)
Forget to test across different email clients
Paste large chunks of untested HTML
Platform-Specific Notes
Testing Recommendations
Always preview in the editor first
Send test emails to multiple providers (Gmail, Outlook, Apple Mail)
Check on both desktop and mobile devices
Verify links and images load correctly
Conclusion
Creating effective email templates requires understanding and working within the constraints of email clients. By following these guidelines, you'll create templates that:
Display consistently across all email clients
Work well on both desktop and mobile devices
Don't break the editor UI
Provide a great user experience
Remember: Simplicity is key in email design. When in doubt, choose the simpler approach that's more likely to work everywhere.