dead-letter

Your .eml files deserve a second life.

dead-letter converts email exports into clean Markdown with YAML front matter — threads split, signatures stripped, attachments extracted, calendars parsed. One file or ten thousand.

✨ Features

• Full-fidelity conversion — HTML sanitization, Gmail/Outlook thread segmentation, inline image handling, and calendar event summaries
• CLI — point it at a file or a directory and go
• Local web UI — dark command-center interface with drag-and-drop import, watch mode, conversion grade badges, processing history, and per-job diagnostics
• Inbox/Cabinet workflow — drop .eml files into an Inbox, let dead-letter organize the Markdown bundles into a Cabinet
• Install validation — dead-letter doctor checks your runtime environment
• Conversion report — opt-in JSON report with per-file diagnostics, including attachment referenced/retained counts for automation and audit
• MCP server — integrate with Claude Desktop, Claude Code, Codex, and other MCP clients
• Claude plugin — one-command install in Claude Code or Cowork with four slash commands (/dead-letter:convert, /dead-letter:summarize, /dead-letter:triage, /dead-letter:cabinet)
• Python API — from dead_letter import convert and you're off

🧠 Built for LLM Pipelines

Raw .eml files are noisy input for downstream LLM and retrieval pipelines — MIME headers, multipart boundaries, duplicated HTML/plain bodies, and encoded attachments all get mixed into the text path.

dead-letter normalizes that into Markdown with YAML front matter, so message text and metadata are ready for chunking or indexing without MIME parsing or base64 cleanup. Default convert() and convert_dir() runs write a single .md per message and keep attachment names in front matter.

If you want the filesystem artifacts separated too, bundle and Cabinet workflows write message.md plus retained decoded files under attachments/. The Markdown is ready for text ingestion, while PDFs, spreadsheets, calendar files, and other retained binary attachments stay cleanly split out for whatever downstream parser you already use.

For direct LLM integration, the MCP server lets Claude Desktop, Claude Code, Codex, and other MCP clients call dead-letter's conversion tools without shelling out.

📊 Token-cost benchmarks

dead-letter's value isn't fewer tokens than every alternative — it's fidelity per token: the cheapest representation that keeps the email intact. Measured across a synthetic corpus of HTML threads, attachments, and newsletters (tokenizer o200k_base, medians):

• ~88% fewer tokens than the raw .eml — a single email with a PDF attachment is ~126k tokens raw vs ~180 converted.
• The only representation that keeps the email whole — thread structure, per-message sender attribution, links, and attachment metadata all survive. Naive text extraction is cheaper precisely because it drops them (0/2 attachments retained vs dead-letter's 2/2).

The benchmark is honest about where it loses: naive extraction is fewer tokens when you don't mind throwing away attachments, links, and thread structure. Full method, the complete table (including those rows), tokenizer disclosure, and a one-command reproduce are in benchmarks/.

📦 Install

With Homebrew on Apple silicon macOS:

brew tap BigCactusLabs/tap
brew insta

... [View full README on GitHub](https://github.com/bigcactuslabs/dead-letter#readme)