Skip to main content
Glama
HTML Email Playbook

HTML Email Playbook

Osama Hassouna · Docs

CI npm license MCP docs

Source for docs.osamahassouna.com — an engineering reference hub I keep open while building. Currently one guide is live, with more landing as I write them.

Live now

HTML Email Playbook

A working reference for hand-building HTML email templates that render reliably across Outlook (Windows desktop, 2007 through 365), Gmail web + mobile, Apple Mail, Yahoo Mail, and the long tail of clients that haven't moved past 2007.

Covers:

  • Structure — doctype, head boilerplate, body container, header / body / footer organization

  • Components — bulletproof CTA buttons (with Outlook VML fallback), spacing patterns, images, inline icons, background images, text

  • Compatibility — Outlook MSO conditional comments, RTL languages, hybrid responsive layouts

  • Production — Gmail 102KB clipping, dark mode, preheader text

  • AI Generation — rules and patterns for AI tools that generate playbook-compliant email HTML

Read it: docs.osamahassouna.com/email-playbook/

There's also a Playground at /email-playbook/playground/ with a live editor, instant preview, and a "From Image" tab that converts a design screenshot into playbook-compliant HTML.

Related MCP server: Temway MCP Server

Use the playbook in your AI workflow

The playbook is published as an MCP server + terminal CLI so AI clients (Claude Desktop, Cursor, Cline, etc.) can pull rules and component patterns directly into their reasoning. The model calls structured tools to fetch the exact patterns from the playbook instead of guessing from training data.

npm install -g email-playbook-mcp

Setup, tool reference, and Claude Desktop / Cursor config snippets: docs.osamahassouna.com/email-playbook/mcp/

There's also a hosted JSON-RPC endpoint at docs.osamahassouna.com/api/mcp if you'd rather not install anything.

License

MIT. Playbook content © Osama Hassouna · osamahassouna.com

Available Tools

5 tools
get_componentA
Read-onlyIdempotent
Inspect

Return the full record for a single component: title, description, narrative body, the primary HTML pattern, list of slots (placeholders the model should fill), VML/responsive flags, and all code examples. Use after list_components to fetch the actual HTML pattern to paste into an email.

Inputs: name (required).

get_playbook_rulesA
Read-onlyIdempotent
Inspect

Return rule pages. format "checklist": each page as its slug, title, description and a short list of the rules to follow, without the body or code; leave out category to get every page in one call (about 16 KB). format "full" (default, needs a category): each page with title, description, checklist, markdown body and all HTML/CSS code examples. Start with the checklists, then fetch the pages you need with get_rule. Components are not included: use list_components / get_component.

Inputs: format, category.

get_ruleA
Read-onlyIdempotent
Inspect

Return one rule page: slug, category, title, description, checklist, and the markdown body, which includes the page's HTML/CSS code. Accepts the full slug (e.g. "compatibility/responsive"), just the page name ("responsive"), or a page link from a body ("/email-playbook/compatibility/responsive/"). Get the slugs from list_categories. Much smaller than fetching the whole category with get_playbook_rules.

Inputs: slug (required), include_examples.

list_categoriesA
Read-onlyIdempotent
Inspect

List all rule categories in the Email Playbook with a one-line description, page count, and the slug and title of each page in it. Categories are: structure (head/body container/header/body/footer), compatibility (Outlook MSO, RTL, responsive), production (Gmail clipping, dark mode, preheader, bulletproof buttons), ai-generation (constraints for AI emitters). Pass a page slug to get_rule to fetch just that page. For reusable components, use list_components instead — they live in a separate dimension and are not returned by get_playbook_rules.

Inputs: no named parameters.

list_componentsA
Read-onlyIdempotent
Inspect

List all reusable email components in the playbook with their metadata: name, subcategory (layout/media/interactive/text), description, whether they require Outlook VML, and whether they are responsive. Use this first to discover what components exist before calling get_component.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 5 tools

    Disambiguation4/5

    get_playbook_rules and get_rule both return rule pages, which could cause confusion, but the descriptions clearly differentiate (bulk/checklist vs single full page). list_categories and get_playbook_rules also overlap in returning rule metadata, but the separation of rules vs components is well-articulated.

    Naming Consistency4/5

    Consistent list_/get_ verb prefixes throughout (list_categories, list_components, get_rule, get_component, get_playbook_rules). Minor noun inconsistency between 'rule' and 'playbook_rules' is the only deviation, still readable and predictable.

    Tool Count5/5

    Five tools is well-scoped for a read-only reference/playbook server, with a clean 2x2 structure of listing and fetching rules and components, plus category listing. Each tool earns its place.

    Completeness4/5

    The surface covers discovery and retrieval for both rule pages and components, which is the core lifecycle for a documentation server. A search tool or a way to fetch multiple specific rules by slug could improve it, but core workflows are fully served.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides SMTP integration for sending HTML emails and specialized prompts for intent detection and client information extraction. It enables LLMs to automate personalized email workflows and structure user communication data.
      -
    • A
      license
      Not graded
      quality
      F
      maintenance
      Let your AI assistant design beautiful emails & layouts — in your Temway workspace. It turns Claude, ChatGPT, Cursor and friends into a visual email & layout authoring studio.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local-first visual design workspace for AI assistants. Compose wireframes and branded multi-page HTML/CSS documents with live preview, annotations, brand and asset libraries, typed data collections, layout validation, PDF export, and draft-only Gmail handoff.
      16
      29 npm
      20
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible agents to analyze a brand website, build a custom email design system, assemble responsive HTML campaigns, QA rendering, and export production-ready email.
      MIT