HTML email development

Email HTML is not web HTML. Clients strip or ignore most CSS properties, block external stylesheets, and render in engines you have not thought about since 2003. The key rules:

• 01
  Use tables for layout. Flexbox and CSS Grid are unsupported in Outlook (Windows) and older Gmail apps. Nest <table> elements to build multi-column layouts.
• 02
  Inline every style. Gmail strips <style> blocks in forwarded mail and some mobile views. Use inline style="" on every element, or let a framework or build tool do it for you.
• 03
  Max width 600-680px. Most preview panes and mobile clients clip wider emails. Set width="600" on the outer table (HTML attribute, not just CSS) for Outlook compatibility.
• 04
  Host images on a CDN. Attach width and height attributes directly on <img> tags so layout does not break when images are blocked by default. Use alt text that still communicates the message.
• 05
  Support dark mode. Apple Mail, Outlook 2021+, and Gmail app (Android) invert colors in dark mode. Use @media (prefers-color-scheme: dark) in a <style> block. Most modern clients support it even when they strip other styles.
• 06
  Always send a plain-text part. MIME multipart/alternative with both text/plain and text/html parts improves deliverability and serves users on screen readers or minimal clients.

Minimal table skeleton

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Your Subject Line</title>
  <!--[if mso]>
  <noscript><xml><o:OfficeDocumentSettings>
    <o:PixelsPerInch>96</o:PixelsPerInch>
  </o:OfficeDocumentSettings></xml></noscript>
  <![endif]-->
</head>
<body style="margin:0;padding:0;background:#f4f4f4;">
  <!-- Outer wrapper -->
  <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
    <tr>
      <td align="center" style="padding:40px 0;">
        <!-- Email card -->
        <table role="presentation" width="600" cellpadding="0" cellspacing="0"
               style="background:#ffffff;border-radius:8px;">
          <tr>
            <td style="padding:40px 48px;">
              <h1 style="margin:0 0 16px;font-family:sans-serif;font-size:24px;">
                Hello!
              </h1>
              <p style="margin:0;font-family:sans-serif;font-size:16px;line-height:1.6;">
                Your message here.
              </p>
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
</body>
</html>

Writing raw email HTML by hand is painful. These tools abstract the table soup and inline CSS away.

Do not run your own SMTP server for transactional mail. IP reputation, bounce handling, and feedback loops are full-time jobs. Pick a provider.

* AWS SES free tier applies to emails sent from EC2 instances or Lambda. Sending from outside AWS costs $0.10/1 000.

import nodemailer from 'nodemailer';

const transport = nodemailer.createTransport({
  host: 'smtp.postmarkapp.com',
  port: 587,
  auth: {
    user: process.env.POSTMARK_API_KEY,
    pass: process.env.POSTMARK_API_KEY,
  },
});

await transport.sendMail({
  from: '"Harbor" <hello@harbor.example>',
  to: user.email,
  subject: 'Welcome to Harbor',
  text: 'Thanks for signing up.',
  html: '<p>Thanks for signing up.</p>',
});

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Harbor <hello@harbor.example>',
  to: [user.email],
  subject: 'Welcome to Harbor',
  html: '<p>Thanks for signing up.</p>',
});

if (error) throw new Error(error.message);

Development: catch all outgoing mail locally

# Mailpit, a maintained Mailhog replacement
docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit

# Then point Nodemailer at localhost:1025 (no auth)
# Open http://localhost:8025 to read caught mail

Since February 2024, Google and Yahoo require bulk senders to have SPF, DKIM, and DMARC configured. Even for low volume you should set these up. They directly affect inbox placement.

Good deliverability is the combined result of technical setup, list hygiene, and sending behaviour. Here is what actually moves the needle:

• 01
  Use a subdomain for transactional mail. Send from mail.harbor.example or notifications.harbor.example rather than your root domain. Reputation problems on one subdomain do not contaminate the other.
• 02
  Handle bounces and complaints immediately. Subscribe to your provider's webhook events for bounce, complaint, and unsubscribe. Suppress those addresses within seconds. ISPs watch your bounce and complaint rates closely.
• 03
  Warm up new IPs and domains. Start with a small volume (a few hundred / day) and ramp up over 2-4 weeks. Jumping from 0 to 50 000 emails/day triggers spam filters.
• 04
  Apple Mail Privacy Protection (MPP) inflates open rates. Since iOS 15, Apple pre-fetches tracking pixels for about 60% of your list. Open rates are no longer a reliable metric. Use click-through rate and conversion instead.
• 05
  One-click unsubscribe (RFC 8058). Required by Google and Yahoo for bulk senders. Add List-Unsubscribe and List-Unsubscribe-Post headers so mail clients display a native unsubscribe button.

Test at three levels: rendering across clients, catching mail during development, and validating authentication records.