dead-letter

dead-letter

Turn `.eml` email exports into clean, local, LLM-ready Markdown.

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

Use it to build a readable email archive, move messages into Markdown-based knowledge systems, or prepare email for RAG and LLM pipelines without feeding raw MIME and base64 into your context window. No account, upload, or API key required.

⚡ Try it

If you already have uv, run dead-letter without installing it globally:

uvx --python 3.12 dead-letter convert message.eml

Or install with Homebrew or pip below. Agents and MCP clients can use the client-specific setup in llms-install.md.

🎯 Common use cases

• Email → Markdown archives — turn exported .eml collections into readable, portable Markdown with structured metadata
• RAG and LLM ingestion — normalize message text, thread structure, links, and attachment metadata before chunking or indexing
• Agent workflows — expose conversion and diagnostics directly to Claude, Codex, and other MCP clients
• Knowledge bases — move email into Markdown-first systems such as Obsidian, static archives, or local search pipelines
• Digital preservation — retain human-readable content and useful message structure without depending on one mail client

✨ 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 — marketplace install in Claude Code or Cowork with five slash commands (/dead-letter:convert, /dead-letter:summarize, /dead-letter:triage, /dead-letter:cabinet, /dead-letter:mbox)
• Portable Agent Skill — teaches skill-aware agents when and how to convert .eml files
• 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.

To separate the filesystem artifacts 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 clients call dead-letter's conversion tools without shelling out. Conversion is local; your chosen MCP host may still send returned email text to a remote model.

📊 Token-cost benchmarks

dead-letter's value isn't fewer tokens than every alternative — it's fidelity per token: keeping useful email structure without carrying raw MIME into context. Measured across an 11-message synthetic corpus of HTML threads, attachments, and newsletters (tokenizer o200k_base, structured thread mode):

• ~88% fewer tokens than the raw `.eml` in the reported aggregate comparison — the attachment category's median is ~126k tokens raw vs ~180 converted.
• Structure survives — thread structure, per-message sender attribution, links, and attachment metadata remain readable. The tested naive baselines are often cheaper because they discard information (0/2 attachment names retained vs dead-letter's 2/2).

Those counts measure the Markdown representation, not the contents of retained binary attachments or downstream answer quality. The shipping default is latest-message mode; the benchmark uses structured mode for a same-thread comparison.

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

📦 Install

Pick one route. The distribution map explains how the channels fit together; installing all of them is not necessary.

With Homebrew on Apple silicon macOS:

brew tap BigCactusLabs/tap

brew install dead-letter

The Homebrew formula installs the CLI (dead-letter convert, dead-letter doctor). Formulas for 0.4.7 and later also install the dead-letter-mcp server; the optional web UI is not included.

With pip:

pip install dead-letter            # core + CLI

pip install 'dead-letter[cli]' # + watchfiles (used by backend/UI watch mode) pip install 'dead-letter[ui]' # + web UI, API server, and watch mode pip install 'dead-letter[mcp]' # + MCP server

Use pipx for an isolated UI or MCP install:

pipx install 'dead-letter[ui]'      # installs dead-letter and dead-letter-ui

Or, for MCP instead:

pipx install 'dead-letter[mcp]' # installs dead-letter and dead-letter-mcp

Or run individual entrypoints without a global package install using uvx:

uvx --python 3.12 dead-letter convert message.eml

uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp

uv caches tools/dependencies and may download Python on first use. These unpinned trial commands do not promise a fresh latest version on every run; see version pinning for a reviewed deployment.

From source:

git clone https://github.com/BigCactusLabs/dead-letter.git

cd dead-letter uv sync --extra dev --locked # all extras

Or choose only the surface you're developing:

uv sync --extra ui --locked # UI only uv sync --extra mcp --locked # MCP only

Agent Skill (any host)

Install the portable Agent Skill into whichever agent you use:

gh skill install BigCactusLabs/dead-letter dead-letter --agent claude-code

gh skill install BigCactusLabs/dead-letter dead-letter --agent codex gh skill install BigCactusLabs/dead-letter dead-letter --agent github-copilot

Needs gh 2.90 or newer. The skill is independent of the Claude plugin. Pin a reviewed skill tag/commit for reproducibility; the default latest release can also be a plugin release. For exact pin syntax, other hosts, manual installation, and discovery metadata, see Agent Discovery.

🚀 Quick Start

CLI — convert a single file:

dead-letter convert message.eml

Convert a whole directory:

dead-letter convert inbox/ --output out/

Generate a JSON conversion report alongside the output:

dead-letter convert inbox/ --output out/ --report

With --output, the report is written to that output directory as .dead-letter-report.json. Without --output, file conversions write the report next to the source message and directory conversions write it to the input directory root.

Check your runtime environment:

dead-letter doctor

Directory conversion scans recursively for .eml files, matches the suffix case-insensitively, skips symlinked files whose resolved targets escape the requested input tree, and deduplicates in-tree symlink aliases that resolve to the same message file.

Web UI — start the local server:

dead-letter-ui --host 127.0.0.1 --port 8765

Open http://127.0.0.1:8765 — on first launch, a setup prompt suggests default Inbox and Cabinet folders. Configure those folders before importing or starting jobs. Skipping dismisses the prompt but leaves those actions gated until setup is completed. Import .eml files with drag and drop or the file picker. Single-file imports use file mode, while multi-file drops create one directory-mode batch job. Mixed drops ask for confirmation before skipping non-.eml files.

The backend enforces a 100 MB per-file import limit for both single and batch uploads; browser batches also have aggregate-size and file-count limits.

From a source checkout, prefix with uv run:

uv run dead-letter convert message.eml

uv run --extra ui dead-letter-ui --host 127.0.0.1 --port 8765

🐍 Python API

from dead_letter import convert

result = convert("message.eml") print(result.subject, result.sender) print(result.output) # path to the generated .md

With options:

from dead_letter import convert, ConvertOptions

result = convert("message.eml", options=ConvertOptions( strip_signatures=True, strip_quoted_headers=True, ))

Strip signature images (logos, social icons) and tracking pixels:

result = convert("message.eml", options=ConvertOptions(

strip_signature_images=True, strip_tracking_pixels=True, ))

When enabled, these filters remove matched images from rendered Markdown and omit stripped inline signature/tracking assets from bundle attachment output.

Bundle conversion (Markdown + attachments + source in one directory):

from dead_letter import convert_