emailmd

emailmd is a markdown-to-email converter that uses MJML under the hood to ensure high compatibility across email clients like Gmail, Outlook, Apple Mail, and Yahoo Mail.

Key capabilities include:

• Email-safe HTML: Bulletproof layouts using MJML.
• Layout Directives: Support for heroes, columns, callouts, and accordions.
• Theming: Brand colors, custom fonts, and automatic dark mode support.
• Buttons: Primary, secondary, and semantic variants using a simple attribute.
• Frontmatter: Metadata and theme overrides defined per email.
• Linting: Checks for deliverability and accessibility.
• Dual Output: Automatic generation of text/plain versions.
• Tooling: Includes a CLI, React builder, MCP server for AI, and reusable partials.

New capabilities (new RenderOptions, new frontmatter keys, new directives, or new warning stages) are introduced in minor versions.

If your code exhaustively matches on union types such as RenderWarning['stage'] or SegmentType, you must include a default case. This ensures your code remains compatible when these unions grow in future minor releases.

The MCP server follows the versioning of the emailmd package:

• The hosted endpoint always runs the latest release.
• The local server (npx emailmd mcp) runs the version currently installed in your environment.

Tool names and result shapes follow the standard emailmd stability policy.

Automatic Styling

Tables automatically inherit theme colors and apply the following styles:

• Header row: Bold text with a 2px bottom border.
• Body rows: Subtle 1px bottom borders between rows.
• Cell padding: 8px vertical, 12px horizontal.

Mobile Best Practices

To ensure tables look good on mobile devices:

• Keep tables simple and narrow.
• Aim for 2–4 columns to avoid horizontal scrolling on small screens.

When using partials, keep the following rules in mind:

• Nesting: Partial expansion happens textually before markdown parsing. You can include directives, buttons, images, and even other partials. Nesting is supported up to 10 levels deep.
• Cycles: Circular includes (e.g., A includes B, and B includes A) are detected and skipped with a warning.
• Frontmatter: If a partial starts with a --- block, it will be stripped with a warning. Frontmatter should reside in the main document, not the partial.
• Naming: Partial names can include letters, digits, _, -, ., and / (useful for namespacing like blocks/footer).
• Code Fences: Include lines inside code fences or indented code blocks are ignored, allowing you to document the syntax itself.

Directives are special block-level sections used to control the layout of an email. They are implemented using the ::: fenced container syntax.

For directives that require content, use a closing ::: tag. For single-line directives like spacer or divider, no content or closing tag is required.

::: directive
Content goes here
:::

Partials are named blocks of markdown that can be reused across multiple emails using the ::: include <name> directive. When you edit a partial, the changes propagate to every email that includes it.

Partials are provided to the render() function via a partials map where the key is the partial name and the value is the markdown string.

In the React builder, you can pass this map to the renderOptions prop to see includes expand live in the preview.

import { render } from 'emailmd';

const { html } = await render(markdown, {
  partials: {
    'legal-footer': `::: footer
**Acme Inc.** · 123 Main St, Portland OR
[Unsubscribe]({{unsubscribe_url}}) · [Preferences]({{prefs_url}})
:::`,
  },
});

Use the theme key to switch the base theme for a single email. Valid values are:

• light (default)
• dark (renders dark for everyone)
• auto (renders light by default but adapts to the reader's dark mode settings)

To customize the dark variant when using theme: auto, provide a dark: map containing snake_case theme overrides. Providing a dark: map automatically implies theme: auto.

Note: Explicitly setting theme: light or theme: dark pins the theme and prevents automatic adaptation to the reader's client settings.

---
theme: auto
dark:
  background_color: "#111827"
  content_color: "#1f2937"
---

Linting findings are categorized into two severity levels:

• warning: Indicates a likely real problem that should be fixed before sending.
• suggestion: Indicates an issue worth reviewing, but which may be intentional (e.g., a transactional email omitting an unsubscribe link).

Accordion interactivity depends on the email client's support for specific CSS/HTML patterns:

• Supported Clients (e.g., Apple Mail, iOS Mail): Panels are interactive and can be collapsed/expanded.
• Unsupported Clients (e.g., Gmail, Outlook): All panels are shown in an expanded state. The content renders as a natural sequence of headings and text.
• Plain-text output: The accordion is flattened into a standard text sequence.

Understanding the difference between these three concepts is key to choosing the right tool: