dead-letter is a tool that converts .eml email export files into clean, local, LLM-ready Markdown, with output that includes YAML front matter. Its core goal is to remove raw MIME and base64 noise from the context while preserving email thread structure, sender attribution, links, and attachment metadata.
Main capabilities include: full-fidelity conversion (HTML sanitization, Gmail/Outlook thread splitting, inline image handling, calendar event summaries), single-file or whole-directory recursive conversion, JSON conversion reports, quality diagnostics (attachment reference/retention counts), optional signature image and tracking pixel stripping, and bundled conversion (Markdown + attachments + source files in the same directory).
There are multiple ways to use it: the CLI can point directly at a file or directory; the local Web UI provides a dark command-center interface with drag-and-drop import, watch mode, conversion level badges, processing history, and per-task diagnostics; the MCP server can integrate with MCP clients such as Claude Desktop, Claude Code, and Codex; the Claude plugin provides five slash commands (/dead-letter:convert, /dead-letter:summarize, /dead-letter:triage, /dead-letter:cabinet, /dead-letter:mbox); the portable Agent Skill can be installed into various agents; and the Python API is called via from dead_letter import convert. Installation supports uv, Homebrew (core CLI only), and pipx.
Use cases: email-to-Markdown archiving, RAG and LLM ingestion, agent workflows, knowledge base migration (such as Obsidian or local search), and digital preservation.
Known limitations: the CLI/Python accepts .eml, flat .mbox exports, and, as of 0.4.5, ZIP/TGZ Takeout downloads; the Web UI supports only EML; the MCP server adds a bounded convert_mbox tool as of 0.4.5. PST, MSG, and live mailbox connections are not supported. As of 0.4.6, the CLI/Python provides optional resumable MBOX import (--mbox-resume). Local single-user single-machine, with no remote server or authentication service; the in-memory job registry resets after restart, and retained binary attachments require a separate parser for text indexing. The license is PolyForm Noncommercial 1.0.0, free for personal, educational, and nonprofit use, with commercial use requiring a separate license.
