Compatibility

What the framework does to help you build emails that render well across popular email clients, plus tips for testing and troubleshooting your templates.

Tailwind CSS

We created @maizzle/tailwindcss, a custom Tailwind CSS 4 configuration that is optimized for styling HTML emails:

• px spacing scale instead of rem
• HEX color palette instead of CSS variables
• mso- utilities for Outlook-specific styles
• email client targeting variants like gmail: or ios:
• prose typography styles optimized for email content
• email-safe defaults for things like box-shadow, border-radius, and more

Syntax lowering

The framework lowers modern Tailwind CSS 4 syntax like nesting, calc() or oklch, so you can safely use sm:, hover:, dark: or even advanced utilities like space-y-* or *: without worrying about email client support.

Components

Maizzle includes many built-in components for building HTML emails, from layout primitives like Container, Row and Column, to visual elements like Button, Img, Heading, CodeBlock and more.

All components have been render-tested in the most popular email clients:

Apple Mail

macOS and iOS

Gmail

Web, Android, iOS

Yahoo! Mail

Web, Android, iOS

Outlook

Windows, macOS, iOS, Android, web

Getting these to render correctly covers most other clients too (like Thunderbird, Samsung Email...), which translates to compatibility with over 95% of email clients used worldwide.

Checks

When developing locally, the dev server scans your template (and every component it imports) for things that may not render well across email clients.

Warnings will show up in the Checks tab of the bottom panel, and you can click the line number on the right to jump to that location in your editor:

There are two kinds of checks:

• Compatibility uses data from caniemail.com to flag CSS or HTML features that are unsupported or partially supported in your target clients.
• Lint are basic structural checks, like missing required tags, a Button without an href, or an image missing an alt attribute.

By default, checks target the four most popular client families (Gmail, Apple Mail, Outlook and Yahoo!), but you may configure or disable them:

export default {
  server: {
    // `checks: false` to turn off entirely
    checks: {
      // `clients: 'all'` to check every client in caniemail's database
      clients: ['gmail', 'apple-mail', 'outlook'],
      // Filter by severity: 'error', 'warning', or 'lint'
      level: 'error',
    },
  },
}

<script setup>
  defineConfig({
    server: {
      checks: {
        clients: ['gmail', 'apple-mail'],
        level: 'error',
      },
    },
  })
</script>

<template>
  <!-- ... -->
</template>

Testing

You should always run render tests in popular email clients before sending to your subscribers. Tools like Testi@, Email on Acid or Litmus can help with that.

Another good practice is to send yourself a test email from the same system you'll use in production, be it your email service provider or your application.

You may also send test emails using the Test panel when developing locally.