Md To Eml

Write in Markdown, send as professional email — works in any email client

Convert Markdown documents with YAML frontmatter into RFC 5322-compliant .eml files ready for governance, newsletter, and stakeholder communication workflows.

When to Use

• Sending formatted content via email clients (Outlook, Thunderbird, etc.)
• Newsletter or governance communication from Markdown sources
• Generating test emails for review before batch sending
• Converting documentation into distributable email format
• Creating email templates with consistent branding
• Stakeholder updates with embedded charts or diagrams

Supported Formatting

Key Features

Header values and --test-to reject control characters before conversion or test-recipient overrides. Source and rendered HTML use the same executable-HTML screening as the HTML converter; scripts, event handlers, and executable URLs stop conversion without replacing an existing email. Literal HTML inside code remains escaped. This screening is not a substitute for sanitizing untrusted input, and conversion does not send email or prove mail-client behavior.

Usage

# Basic conversion
node skills/md-to-eml/scripts/md-to-eml.cjs newsletter.md

# With test recipient override (safe preview)
node skills/md-to-eml/scripts/md-to-eml.cjs newsletter.md --test --test-to me@example.com

# Embed images as CID attachments
node skills/md-to-eml/scripts/md-to-eml.cjs update.md --inline-images

# Debug mode (saves intermediate HTML)
node skills/md-to-eml/scripts/md-to-eml.cjs update.md --debug

Options Reference

Frontmatter Format

The YAML frontmatter maps directly to RFC 5322 email headers:

---
to: team@example.com
from: sender@example.com
subject: 📊 Weekly Update - Sprint 42
cc: manager@example.com
reply-to: noreply@example.com
---

Email Client Compatibility

Test Mode Workflow

1. Write your newsletter/update in Markdown with frontmatter
2. Convert with --test --test-to your@email.com
3. Open the .eml file in your email client
4. Review formatting, images, links
5. Convert again without --test for production
6. Send via your email client or automation

Mermaid Diagrams in Email

Email clients cannot execute JavaScript. The supported simple graph/flowchart subset becomes node and relationship tables. Unsupported diagram types or syntax retain their complete original source in a labeled code block, not a rendered diagram. Pre-render to PNG when a visual diagram is required.

┌─────────────────┐
│ Original Mermaid │ → Table Fallback
└─────────────────┘

flowchart LR    →   | Step | Description |
  A --> B           | A    | Start       |
  B --> C           | B    | Process     |
                    | C    | End         |

For high-fidelity diagrams, pre-render to PNG and include as images.

Troubleshooting

Limitations

• Email clients cannot execute JavaScript — simple flowcharts use tables; unsupported diagrams retain labeled source
• Complex CSS layouts may render differently across clients (Outlook vs Gmail vs Apple Mail)
• Inline images add to email size — consider linking for large image sets
• Some clients strip CSS — design for graceful degradation

Requirements

• Node.js 24+
• pandoc (for Markdown to HTML conversion)
• Shared runtime: keep the complete scripts/shared/ directory at the same relative location, including the image-path and HTML-screening helpers and their transitive imports.

Muscle Script

skills/md-to-eml/scripts/md-to-eml.cjs

Conversion Acceptance Decision Table

Related Skills

• md-to-html - sister converter for web page output
• md-to-word - sister converter for Word document output
• Markdown linting - validate the source with the project's linter or the lint-clean-markdown skill

Falsifiability

• This skill is wrong if generated .eml files fail to render correctly in Outlook or Thunderbird, or if MIME structure is rejected by mail servers
• The header format is stale if RFC 5322 compliance requirements change or major mail clients alter their parsing
• Not earning tokens if users must manually fix the same MIME issues on every conversion