Professional HTML Emails: Layout, Templates, Sending & Testing

---
name: professional-html-email
description: Design, build and ship professional HTML emails (proposals, onboarding, outreach, receipts) that render in Gmail, Outlook and Apple Mail. Use when an agent must write or template a customer-facing email, review one before sending, or fix one that "looks like a wall of text".
---

# Professional HTML Email: the field guide

Use this whenever you write, template, review or send a customer-facing email. It is built from a production workflow where an agent drafts the email, the server renders a branded template, a human approves the exact saved copy, and test copies are checked in a real Gmail inbox first.

The goal: an email that looks designed, reads in 20 seconds, has one obvious next step, and lands in the inbox with the right sender and Reply-To.

---

## 1. The five rules that matter most

1. **Tables + inline styles.** Email clients ignore most modern CSS. Lay out with `<table role="presentation">`, put every style inline, and keep the content column at **600–620px** max width.
2. **One message, one action.** Every email has exactly one primary button. Everything else supports that click.
3. **Agents write text; templates write HTML.** Let the agent (or person) produce plain text. A server-side function turns it into the branded HTML. Never let free-form HTML from a model reach a customer.
4. **Preview what was saved, not what was typed.** Review the stored draft (recipient, sender, Reply-To, subject, body, images, link) exactly as it will send.
5. **Send yourself a test first.** Real inboxes reveal broken images, spam placement and wrong Reply-To addresses that previews hide.

---

## 2. Anatomy of a professional email

Top to bottom:

| Block | Purpose | Notes |
|---|---|---|
| Preheader | Inbox preview text | Hidden span, 40–90 chars, complements the subject |
| Header band | Brand recognition | Logo on the brand color, 3px accent rule underneath |
| Greeting + 2–4 short paragraphs | The why | 1–3 sentences each; no walls of text |
| Inline images | Proof (screenshots, GIFs) | Placed right where the text refers to them |
| Bullets | Questions or options | Use for anything the reader must answer |
| Offer card | The what + price | Title, short description, big total, button |
| How it works (3 steps) | Removes fear | Icon + bold step + one line each |
| Sign-off | Human close | "Thank you," stays *after* the card |
| Signature | Trust | Logo, team name, email, website |
| Footer | Compliance | Postal address + unsubscribe for marketing mail |

### Copy rules
- **Subject:** specific and short. If addressing a person at an office, put it in the subject: `Attention: Dana - Website issue and emergency page option`. Use a plain hyphen; some clients mangle em dashes in subjects.
- **First line** says why you are writing. Second paragraph shows proof. Third makes the offer.
- **Questions go in bullets**, never buried mid-paragraph ("please let us know whether you have access to: • your domain • your business profile").
- **Price appears once, big, in the card.** Don't repeat it in three paragraphs.
- **No claims you can't back up.** Avoid "guaranteed", "100%", unverifiable partner names.
- **Never write the signature into the message.** The template adds it; duplicates look careless.

---

## 3. Visual system

- **Fonts:** web fonts don't load in most clients. Use a stack: `'Helvetica Neue',Helvetica,Arial,sans-serif`. Body 15px / line-height 24px; card title 19–20px bold; big price 28px bold; small print 12–13px.
- **Colors:** dark ink text (`#0D1A33`-ish) on white; muted text `#3D4B63`; one accent for links and the button. White text on the accent must pass contrast (pick a blue around `#1F63E6`, not a pale brand blue).
- **Never light-on-light or dark-on-dark.** A white card on a light gray page is fine; gray text on a gray card is not.
- **Page:** light gray background (`#F3F5F9`), white rounded card (`border-radius:16px`, `border:1px solid #E4E8F0`).
- **Logos:** use the version made for the background it sits on (light logo on a dark band, dark logo on white). Some brands require a white background behind the logo; respect brand rules over style preferences. Host the real, already-deployed logo file. Don't invent new paths that 404 until a deploy.
- **Icons:** small 3D or flat icons at 40–56px make steps scannable. Host them as **PNG** at 2x size (e.g. 112px for 56px display). No SVG, no WebP (Outlook and some webmail drop them).

---

## 4. Images

- **Hosted images:** absolute `https://` URLs, always with `width`, `height`, `alt`, `style="display:block;border:0"`.
- **Inline (CID) images** for screenshots/GIFs that must show without "load images": attach with a `Content-ID` and reference `src="cid:..."`. Animated GIFs play in most clients; the first frame must make sense on its own (Outlook desktop shows only frame one).
- Keep each image under ~1–2 MB and the whole email under ~10 MB. **Gmail clips HTML over ~102 KB**: keep markup lean (no repeated giant inline styles, no base64 images in HTML).
- Let the author choose placement with a marker line, e.g. `[images]` on its own line in the plain text, so proof sits next to the sentence that mentions it.

---

## 5. The bulletproof template

A trimmed, working skeleton. Server code fills the `{{ }}` parts and **HTML-escapes every value**.

```html
<div style="background:#F3F5F9;padding:24px 10px;font-family:'Helvetica Neue',Helvetica,Arial,sans-serif">
  <span style="display:none;max-height:0;overflow:hidden">{{preheader}}</span>
  <table role="presentation" width="100%" cellpadding="0" cellspacing="0"
    style="max-width:620px;margin:0 auto;background:#FFFFFF;border:1px solid #E4E8F0;border-radius:16px;border-collapse:separate">
    <!-- Header band -->
    <tr><td style="padding:22px 32px;background:{{brandDark}};border-radius:15px 15px 0 0;border-bottom:3px solid {{accent}}">
      <img src="{{logoOnDarkUrl}}" alt="{{brandName}}" width="220" height="35" style="display:block;border:0">
    </td></tr>
    <!-- Message -->
    <tr><td style="padding:28px 32px 8px">
      <p style="margin:0 0 16px;font-size:15px;line-height:24px;color:#0D1A33">{{paragraph}}</p>
      <!-- repeat paragraphs; bullets: -->
      <ul style="margin:0 0 16px;padding-left:22px;font-size:15px;line-height:24px;color:#0D1A33">
        <li style="margin:0 0 6px">{{bullet}}</li>
      </ul>
      <!-- Offer card -->
      <table role="presentation" width="100%" cellpadding="0" cellspacing="0"
        style="margin:8px 0 22px;border:1px solid #D3DAE6;border-radius:16px;background:#F7F9FC;border-collapse:separate">
        <tr><td style="padding:22px 24px 0">
          <p style="margin:0 0 3px;font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#3D4B63;font-weight:bold">Your proposal</p>
          <p style="margin:0;font-size:20px;line-height:27px;color:#0D1A33;font-weight:bold">{{title}}</p>
          <p style="margin:6px 0 0;font-size:14px;line-height:21px;color:#3D4B63">{{description}}</p>
        </td></tr>
        <tr><td style="padding:18px 24px 0">
          <table role="presentation" width="100%" style="background:#FFFFFF;border:1px solid #E4E8F0;border-radius:12px;border-collapse:separate">
            <tr><td style="padding:14px 16px">
              <p style="margin:0;font-size:28px;line-height:34px;font-weight:bold;color:#0D1A33">{{total}}</p>
              <p style="margin:2px 0 0;font-size:13px;color:#3D4B63">{{hours}} &times; {{rate}}/hour</p>
            </td></tr>
          </table>
        </td></tr>
        <!-- Bulletproof button: a block link, not an image -->
        <tr><td style="padding:18px 24px 6px">
          <a href="{{link}}" style="display:block;padding:15px 22px;border-radius:12px;background:{{accent}};color:#FFFFFF;font-size:16px;font-weight:bold;text-align:center;text-decoration:none">Review your proposal &amp; get started &rarr;</a>
        </td></tr>
        <tr><td style="padding:4px 24px 18px;text-align:center">
          <p style="margin:0;font-size:12px;color:#3D4B63">Or copy this link: <a href="{{link}}" style="color:{{accent}};word-break:break-all">{{link}}</a></p>
        </td></tr>
      </table>
      <p style="margin:0 0 16px;font-size:15px;line-height:24px;color:#0D1A33">Thank you,</p>
    </td></tr>
    <!-- Signature -->
    <tr><td style="padding:0 32px 28px">
      <table role="presentation" cellpadding="0" cellspacing="0" style="border-left:3px solid {{accent}}"><tr><td style="padding:4px 0 4px 14px">
        <img src="{{logoOnLightUrl}}" alt="{{brandName}}" width="165" height="35" style="display:block;border:0;margin:0 0 8px">
        <p style="margin:0;font-size:14px;font-weight:bold;color:#0D1A33">The {{brandName}} team</p>
        <p style="margin:2px 0 0;font-size:13px;color:#3D4B63">
          <a href="mailto:{{email}}" style="color:{{accent}};text-decoration:none">{{email}}</a> &middot;
          <a href="{{website}}" style="color:{{accent}};text-decoration:none">{{websiteLabel}}</a></p>
      </td></tr></table>
    </td></tr>
  </table>
</div>
```

"How it works" steps: a table row per step, icon cell (`width:44px`, 40px PNG) + text cell (bold `1. Step title` + one muted line). Keep steps true for every recipient (for example: review, authorize securely with nothing charged until work starts, we start).

Always send a **plain-text alternative**: the same message, a "Your proposal" block with the title, price line and raw link, and a `--` signature.

---

## 6. Composer pattern (agents and humans share it)

```
compose(brand, message, proposal?, link?, inlineImages[], clientLogo?) -> { text, html }
```
- Escape everything, then add markup: blank line = paragraph, lines starting with `•` or `-` = bullets, bare `https://` URLs = links (display without the scheme).
- Detect a closing line ("Thank you,", "Best regards,") and render it after the offer card, so the sign-off is last.
- Brand config (sender, Reply-To, signature lines, logos, accent, onboarding URL) lives in **one constants file**. Templates read it; nothing is hardcoded twice.
- A client logo (https only, validated) can show as "Prepared for [logo] Client Name" at the top of the card for personalization.
- Unique links: give each customer a random-token link (e.g. 48 hex chars) that opens their own prefilled page; never put names or prices in the URL.

---

## 7. Sending safely

- **Sender identity is part of the design.** From name/address, Reply-To and signature must all match the brand. A correct body with the wrong Reply-To still looks wrong.
- **The Reply-To must be able to receive mail.** If the domain has no MX records, set up inbox forwarding first, then verify with a real test message. Check the spam folder too; add a filter so forwarded replies are never marked spam.
- **Authenticate the domain:** SPF, DKIM and DMARC. With `p=reject`, anything sending as the domain without its DKIM key is rejected.
- **Approval gate:** a person approves the exact saved draft. Store a fingerprint of recipient, sender, Reply-To, content hash, attachments, offer version/price and scheduled time; recompute it at send time. Any difference voids approval and blocks the send. A newer draft supersedes (unapproves) older ones.
- **Marketing mail** needs a physical postal address and an unsubscribe link. Some sending systems allow only one outreach email per recipient: send internal tests as transactional so you don't burn that slot.
- **Open tracking is an estimate.** Gmail and others fetch images through proxies; scanners click links. Count proxy opens separately, never treat them as a human read, and disclose tracking if your platform requires it. First-party signals (the customer opening their unique link) are more reliable.
- **Exclude yourself from analytics:** add a `preview=1` flag to links in internal test copies and admin "open" buttons, and don't count those visits.

---

## 8. Test like it matters

1. **Render** the HTML in a headless browser at 620px and 375px. Check: no horizontal scroll, logo visible on its band, button full width on mobile, images sized correctly.
2. **Send a [TEST] copy to an internal inbox only** (recipient fixed in code, not taken from the request). Open it in Gmail web and on a phone.
3. Check in the real inbox: From name, Reply-To (hit Reply and look), images loaded, GIF animates, link opens the right page, nothing clipped ("[Message clipped]"), not in Spam/Promotions.
4. Read the plain-text version once.
5. Only then approve the client copy.

---

## 9. Pre-send checklist

- [ ] Subject specific, no em dash, "Attention: Name" if addressed to someone at an office
- [ ] Preheader set
- [ ] One primary button; link is the customer's own unique link
- [ ] Paragraphs ≤ 3 sentences; questions as bullets
- [ ] Images placed by the text that mentions them; all have alt text
- [ ] Logo correct for its background; brand rules respected
- [ ] Price shown once, clearly, with hours × rate if relevant
- [ ] Signature from the template only (not typed in the message)
- [ ] From, Reply-To and signature all match the brand; Reply-To can receive mail
- [ ] Footer address + unsubscribe for marketing mail
- [ ] Plain-text version reads well
- [ ] Test copy checked in a real inbox; approval recorded on the exact saved draft

---

## 10. Common failures and fixes

| Symptom | Cause | Fix |
|---|---|---|
| "Looks like a wall of text" | Long paragraphs, no structure | Shorter paragraphs, bullets, offer card, steps |
| Broken logo | New file path not deployed yet / SVG / WebP | Use the live hosted PNG; deploy before sending |
| Logo invisible | Light logo on white or dark logo on dark | Use the matching logo variant or a header band |
| Replies go to the wrong brand | Reply-To left on another inbox | Set Reply-To per brand; verify by replying to a test |
| Replies vanish | Reply-To domain has no MX | Add forwarding/MX, test, check spam |
| Signature missing or wrong | Gateway signature from another brand, or collapsed by Gmail | Render the signature in the template; make it visual (logo + name) |
| Email clipped | HTML > ~102 KB | Remove inline bloat and base64 images |
| Opens look inflated | Image proxies, your own views | Count proxies separately; tag internal links `preview=1` |
| Approved email changed | Edits after approval | Fingerprint check at send; require fresh approval |