HTML Email Playbook

io.github.OsamaHassounaPublished by GitHub account OsamaHassounav0.8.0Updated Nov 7, 2026

Teaches AI to write HTML email that renders in Outlook, Gmail, and Apple Mail. 21 rules, 6 comps.

The publisher's own server: Playbook

VerifiedStreamable HTTPWeb executableDeveloper ToolsMedia & Design

Overview

AI-generated overview

A read-only knowledge server that gives an assistant HTML email rules and code patterns that render in Outlook, Gmail and Apple Mail.

What you can do
  • Browse rule categories and their pages, with page counts and slugs
  • Fetch rule pages as a compact checklist or in full with HTML/CSS code
  • Look up a single rule page by full slug, short name or page link
  • List reusable components such as buttons, spacing, images and icons
  • Retrieve one component's HTML pattern, slots and VML/responsive flags
When to use it
Useful when an assistant composes or edits HTML email and should follow known-good patterns instead of guessing from training data, for example building a welcome email or converting a design image into email HTML. It only supplies guidance and code; it does not send, preview or validate email.
Requirements
Runs as a local npm package via npx or a global install, or as a hosted JSON-RPC endpoint. No account, API key or authentication is needed. Optional environment variables EMAIL_PLAYBOOK_NO_STALE_NOTICE and EMAIL_PLAYBOOK_STALE_DAYS control the stale-content notice.
Before you install
Read-only and documented as having no inbox access, no email credentials and no network calls of its own. A locally installed copy can fall behind the hosted content, so the README advises installing the latest version rather than pinning one. Generated HTML is not validated or previewed by this server.

Installation

In SourceWeft

  1. Open HTML Email Playbook in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.OsamaHassouna%2Femail-playbook-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "html-email-playbook": {
      "type": "http",
      "url": "https://docs.osamahassouna.com/api/mcp"
    }
  }
}

README

email-playbook-mcp

[npm] [license] [MCP]

[wellknown status]

Stop AI models from generating broken HTML email. This MCP server + CLI feeds them the patterns that actually render in Outlook 2007+, Gmail, and Apple Mail — drawn from the HTML Email Playbook.

Without it, your model invents flex and grid (no email client supports those), hardcodes table widths that overflow on mobile, forgets the VML fallback for Outlook buttons, and makes up footer disclaimers that weren't in your design.

With it, the model calls structured tools to pull the exact patterns from the playbook and composes emails using those, instead of guessing from training data.

🔒 No email permissions, no inbox access. This is a knowledge MCP — it returns playbook rules and HTML patterns. It never reads your mail, sends mail, or asks for Gmail/Outlook/SMTP credentials. Confusable with inbox-integration MCPs but it's a different category entirely.

Install

bash
# Global install (standard)npm install -g email-playbook-mcp
# Or run on demand without installingnpx -y email-playbook-mcp@latest

Safe to install

  • One dependency — the official MCP SDK (@modelcontextprotocol/sdk), nothing else.
  • No postinstall scripts — installing runs no arbitrary code.
  • Read-only, no inbox — the tools only return playbook content. It never reads, sends, or touches email, never opens your inbox, and makes no network calls of its own.

Keeping it current

The playbook grows with new pages and fixes, so install email-playbook-mcp@latest and never pin a version in your client config. The hosted endpoint is always current.

A local copy can still fall behind (a pinned version, a cached global install). When the bundled rules are more than 90 days old, the local server says so, without any network call:

  • MCP server: one short update note in the server instructions and on the first tool result of a session, addressed to the AI client, so it can tell you how to update.
  • CLI: one line on stderr; stdout stays clean JSON.
VariableEffect
EMAIL_PLAYBOOK_NO_STALE_NOTICE=1Turns the note off.
EMAIL_PLAYBOOK_STALE_DAYS=180Changes the age that triggers it (default 90).

Use it in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json
{  "mcpServers": {    "email-playbook": {      "command": "email-playbook-mcp"    }  }}

Restart Claude Desktop. The playbook tools appear in the model's tool list. Ask it to build an email and it'll call them automatically.

What happens under the hood

For an image-to-email or "build me a welcome email" prompt, the model typically calls:

1. list_categories                                    ← orient, page slugs2. get_playbook_rules({ format: "checklist" })        ← every page's rules, ~16 KB3. get_rule({ slug: "compatibility/responsive" })     ← just the pages it needs4. list_components → get_component({ name: "buttons" }) ← components it needs5. compose final HTML using those exact patterns

You don't write that prompt by hand — the model orients itself via the tool descriptions.

Use it in Cursor

Edit ~/.cursor/mcp.json:

json
{  "mcpServers": {    "email-playbook": {      "command": "email-playbook-mcp"    }  }}

Cline / Continue / Windsurf and other MCP-aware clients use the same shape — point a command entry at email-playbook-mcp.

Use it as a CLI

The same package ships a second binary for direct query + scripting:

bash
$ email-playbook get-component buttons | jq '{name, slots, requires_vml}'{  "name": "buttons",  "slots": ["text", "url", "background_color", "text_color", "width_px", "height_px"],  "requires_vml": true}

Other commands: list-categories, list-components, get-rules [category] [--checklist], get-rule <slug> [--examples]; add --md to get-rules / get-rule for readable markdown instead of JSON. The MCP tool names work as command names too (get_playbook_rules, get_rule, ...). Help text is generated from the bundled spec at runtime, never stale. Run email-playbook --help.

Run without installing globally:

bash
npx -y -p email-playbook-mcp email-playbook list-categories

Tools

ToolReturns
list_categoriesThe 4 rule categories with page counts and page slugs
get_playbook_rules({ category?, format? })Rule pages: full (text + code, default, one category) or checklist (the rules to follow; leave out category for every page, about 16 KB)
get_rule({ slug, include_examples? })One rule page with its code (compatibility/responsive or responsive); include_examples: true adds the code as a separate array
list_componentsAll 6 components with metadata
get_component({ name })One component: HTML pattern, slots, VML/responsive flags

Components live in a separate dimension — use list_components / get_component, not get_playbook_rules.

What's in the playbook

SurfaceCountCovers
structure (rules)5Doctype, head, body container, header, body, footer
compatibility (rules)3Outlook MSO, RTL languages, responsive
production (rules)6Gmail 102KB clip, dark mode, force light, email signatures, preheader, bulletproof buttons
ai-generation (rules)7Absolute rules, asset policy, content fidelity, image placeholders, link tokens, output format, handoff checklist
Components6Buttons, spacing, images, inline icons, background images, text

The ai-generation category is the one to fetch first for image-to-email tasks. It encodes rules that override training-data instincts — use {{cta_url}} not https://example.com, reproduce only what's in the source, use placehold.co PNG blocks for every image you weren't given a real URL for, return HTML only.

What it doesn't do

  • Doesn't send email — generate the HTML here, send it through your existing platform.
  • Doesn't render previews — the Playground does (with a "From Image" tab if you have a screenshot).
  • Doesn't validate existing HTML — manual pass via the Handoff Checklist.

Hosted alternative

No install? Point any JSON-RPC 2.0 client at https://docs.osamahassouna.com/api/mcp. Same tools, same content, no auth.

bash
curl -X POST https://docs.osamahassouna.com/api/mcp \  -H "Content-Type: application/json" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

License

MIT © Osama Hassouna

Source: mcp/README.md at commit 69f27ac

Tools

5

list_categories

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.

Takes no parameters.

get_playbook_rules

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.

Parametersformatcategory

get_rule

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.

Parametersslugrequiredinclude_examples

list_components

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.

Takes no parameters.

get_component

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.

Parametersnamerequired

Version history

3
  1. v0.8.0LatestOct 31, 2026
  2. v0.7.0Oct 17, 2026
  3. v0.6.3Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Playbook integrations

Playbook

com.playbookOfficial publisher

Playbook's remote MCP server lets an AI assistant search, organize, upload and share creative media files and folders in a Playbook media backend.

Streamable HTTPWeb executableAuth
Files & StorageCredential requiredOct 24, 2026