How to Build Salesforce Marketing Cloud Email Templates That Actually Work: An MJML Tutorial

The Problem with Marketing Cloud’s Email Builder

If you’ve spent any time building emails in Salesforce Marketing Cloud, you’ve probably experienced the frustration. The drag-and-drop Content Builder is supposed to make email creation simple, but it often creates more problems than it solves:

Inconsistent rendering across email clients
Limited design flexibility for complex layouts
Bloated HTML code that affects deliverability
Mobile responsiveness issues that break on certain devices
Spacing and alignment problems that look different in Outlook vs Gmail

When your email campaigns depend on pixel-perfect designs and reliable cross-client compatibility, Marketing Cloud’s built-in tools often fall short. This is where MJML becomes a game-changer.

What is MJML and Why Use It?

MJML (Mailjet Markup Language) is an open-source framework designed specifically for creating responsive email templates. It uses semantic markup that compiles into bulletproof HTML that works across all major email clients.

Key Benefits for Marketing Cloud Users:

Guaranteed mobile responsiveness without complex media queries
Cross-client compatibility (yes, even Outlook)
Clean, lightweight HTML that improves deliverability
Faster development time with reusable components
Better maintainability with semantic markup

When to Use MJML for Marketing Cloud:

Complex multi-column layouts
Custom branded designs that don’t fit standard templates
Campaigns requiring perfect cross-client rendering
When you need precise control over spacing and typography
Templates that will be reused across multiple campaigns

Prerequisites

Before we start, ensure you have:

Basic HTML/CSS knowledge
Access to create templates in Marketing Cloud
Visual Studio Code (free download)
Understanding of Marketing Cloud’s template structure (slots, content areas)

Step 1: Download and Install Visual Studio Code

Visit https://code.visualstudio.com/
Download the version for your operating system
Run the installer with default settings
Launch Visual Studio Code

Step 2: Install the MJML Extension

In VS Code, click the Extensions icon in the left sidebar (or press Ctrl+Shift+X)
Search for “MJML”
Install the “MJML” extension by mjmlio (the official one)
This extension provides:
- Live preview functionality
- Syntax highlighting and auto-completion
- Built-in linting for error detection
- One-click HTML export

Alternative Installation: You can also find this extension on GitHub or the Visual Studio Marketplace.

Step 3: Create Your First MJML Template

Create a new file in VS Code
Save it as salesforce-template.mjml
Add this starter template:

xml

<mjml>
  <mj-head>
    <mj-title>Salesforce Marketing Cloud Template</mj-title>
    <mj-preview>Preview text appears here in inbox</mj-preview>
    <mj-attributes>
      <mj-all font-family="Arial, sans-serif" />
      <mj-text font-size="14px" color="#333333" line-height="1.5" />
    </mj-attributes>
  </mj-head>
  
  <mj-body background-color="#f4f4f4">
    <mj-raw>
      <!-- Company Header -->
    </mj-raw>
    
    <mj-section background-color="#ffffff" padding="20px">
      <mj-column>
        <mj-text font-size="24px" color="#2c3e50" align="center" font-weight="bold">
          Your Company Name
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-raw>
      <!-- Hero Section -->
    </mj-raw>
    
    <mj-section 
      background-url="https://via.placeholder.com/600x300/3498db/ffffff?text=Hero+Image" 
      background-size="cover" 
      background-repeat="no-repeat"
      padding="60px 20px">
      <mj-column width="600px">
        <mj-text 
          align="center" 
          color="#ffffff" 
          font-size="36px" 
          font-weight="bold"
          text-shadow="2px 2px 4px rgba(0,0,0,0.5)">
          Your Amazing Offer
        </mj-text>
        <mj-button 
          background-color="#e74c3c" 
          color="#ffffff"
          font-size="16px"
          padding="15px 30px"
          border-radius="25px">
          Get Started Now
        </mj-button>
      </mj-column>
    </mj-section>

    <mj-raw>
      <!-- Main Content Area -->
    </mj-raw>
    
    <mj-section background-color="#ffffff" padding="30px">
      <mj-column>
        <mj-text>
          <!-- Marketing Cloud Content Slot -->
          <div data-type="slot" data-key="main-content" data-label="Main Content Area">
            <h2>Drop your content blocks here</h2>
            <p>This is where your dynamic content will appear in Marketing Cloud.</p>
          </div>
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-raw>
      <!-- Two Column Section -->
    </mj-raw>
    
    <mj-section background-color="#f8f9fa" padding="30px">
      <mj-column width="50%" padding="10px">
        <mj-image 
          src="https://via.placeholder.com/250x150/95a5a6/ffffff?text=Feature+1" 
          alt="Feature 1"
          border-radius="8px" />
        <mj-text font-size="18px" font-weight="bold" color="#2c3e50">
          Feature One
        </mj-text>
        <mj-text>
          Description of your first key feature or benefit.
        </mj-text>
      </mj-column>
      
      <mj-column width="50%" padding="10px">
        <mj-image 
          src="https://via.placeholder.com/250x150/95a5a6/ffffff?text=Feature+2" 
          alt="Feature 2"
          border-radius="8px" />
        <mj-text font-size="18px" font-weight="bold" color="#2c3e50">
          Feature Two
        </mj-text>
        <mj-text>
          Description of your second key feature or benefit.
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-raw>
      <!-- Footer -->
    </mj-raw>
    
    <mj-section background-color="#2c3e50" padding="30px">
      <mj-column>
        <mj-text color="#ffffff" align="center" font-size="12px">
          © 2025 Your Company Name. All rights reserved.
          <br><br>
          You received this email because you subscribed to our newsletter.
          <br>
          <a href="%%unsubscribe_url%%" style="color: #3498db;">Unsubscribe</a> | 
          <a href="%%profile_center_url%%" style="color: #3498db;">Update Preferences</a>
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-raw>
      <!-- Marketing Cloud Tracking -->
      <custom name="opencounter" type="tracking"/>
    </mj-raw>
    
  </mj-body>
</mjml>

Step 4: Preview Your Template

Open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on Mac)
Type “MJML” and select “MJML: Open Preview to the Side”
You’ll see a live preview of your email template
Make adjustments to the MJML code and watch the preview update in real-time

Step 5: Understanding Key MJML Components

Essential MJML Tags for Marketing Cloud:

<mj-section> – Horizontal container, like a row
<mj-column> – Vertical container within sections
<mj-text> – Text content with built-in responsiveness
<mj-button> – Call-to-action buttons that work everywhere
<mj-image> – Responsive images with automatic optimization
<mj-raw> – Raw HTML for comments and Marketing Cloud-specific code

Marketing Cloud Integration Points:

xml

<!-- Content Slots for Dynamic Content -->
<div data-type="slot" data-key="unique-key" data-label="User-Friendly Name">
  Default content here
</div>

<!-- Personalization Strings -->
<mj-text>
  Hello %%FirstName%%!
</mj-text>

<!-- Unsubscribe Links -->
<a href="%%unsubscribe_url%%">Unsubscribe</a>

<!-- Tracking Pixel -->
<custom name="opencounter" type="tracking"/>

Step 6: Advanced MJML Techniques

Responsive Breakpoints:

xml

<mj-section>
  <mj-column width="100%" medium-width="50%">
    <!-- Stacks on mobile, side-by-side on desktop -->
  </mj-column>
</mj-section>

Custom CSS:

xml

<mj-head>
  <mj-style>
    .custom-class {
      color: #e74c3c !important;
    }
  </mj-style>
</mj-head>

Conditional Content for Outlook:

xml

<mj-raw>
  <!--[if mso]>
    <div style="font-family: Arial, sans-serif;">
      Outlook-specific content
    </div>
  <![endif]-->
</mj-raw>

Step 7: Export to HTML

Open the Command Palette
Type “MJML” and select “MJML: Export HTML”
Choose where to save your HTML file
The exported HTML is optimized for email clients and ready for Marketing Cloud

Step 8: Import into Marketing Cloud

In Marketing Cloud, go to Email Studio > Content Builder
Click Create > Template
Choose Paste HTML
Copy and paste your exported MJML HTML
Name your template
Important: Set template type to “Template” for reusability
Save and test across different email clients

Step 9: Testing Your Template

Marketing Cloud Testing:

Create a test email using your new template
Use Preview and Test to check rendering
Send test emails to multiple email clients
Verify that slots work correctly with dynamic content

Recommended Testing Checklist:

Gmail (desktop and mobile)
Outlook 2016/2019/365
Apple Mail (iOS and macOS)
Yahoo Mail
Outlook.com

Troubleshooting Common Issues

Template Import Errors:

Remove any <style> tags that might conflict with Marketing Cloud
Ensure all URLs are absolute (not relative)
Check that slot syntax is correct

Rendering Problems:

MJML automatically handles most cross-client issues
For persistent problems, add custom CSS in <mj-head>
Use <mj-raw> for Outlook-specific fixes

Marketing Cloud Compatibility:

Always test personalization strings in preview mode
Verify tracking pixels are firing correctly
Check that unsubscribe links are working

Best Practices for MJML + Marketing Cloud

Performance Optimization:

Keep images under 100KB each
Use web-safe fonts for broader compatibility
Optimize file sizes before referencing in templates

Maintainability:

Use consistent naming for slots and content areas
Comment your MJML code for future reference
Create reusable components for headers/footers

Design Guidelines:

Maximum width of 600px for email content
Use high contrast colors for accessibility
Test with images disabled

Marketing Cloud Integration:

Plan your slot structure before coding
Use descriptive slot labels for content creators
Consider mobile-first design principles

Advanced Workflow Tips

Template Organization:

Create a folder structure for different campaign types
Use version control (Git) for template management
Document personalization fields used

Automation Opportunities:

Set up build scripts to automatically export HTML
Create template libraries for different brands
Use MJML includes for shared components

Team Collaboration:

Share MJML files with designers for easy updates
Create style guides using MJML attributes
Train content creators on slot usage

Need help with complex Salesforce and Marketing Cloud integrations? Contact Knihter for professional Salesforce Marketing Cloud development services. We specialize in custom email templates and advanced automation implementations.

Related Services:

Custom MJML email template development for Marketing Cloud
Marketing Cloud Connect configuration and troubleshooting
Cross-platform email template optimization and testing
Salesforce and Marketing Cloud developer training and consulting