dead-letter

dead-letter

.eml形式のメールエクスポートを、ローカルで使えるLLM対応のクリーンなMarkdownに変換します。

dead-letterは、.eml形式のメールエクスポートをYAMLフロントマター付きのクリーンなMarkdownに変換します。スレッドの分割、署名の除去、添付ファイルの抽出、カレンダーの解析に対応しています。1ファイルでも1万ファイルでも処理できます。

読みやすいメールアーカイブの構築、メッセージのMarkdownベースのナレッジシステムへの移行、または生のMIMEやbase64をコンテキストウィンドウに投入せずに、RAGやLLMのパイプライン向けにメールを準備する際にご利用ください。アカウント登録、アップロード、APIキーは不要です。

⚡ お試しください

すでにuvをお使いの場合は、グローバルにインストールせずにdead-letterを実行できます。

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

または、以下からHomebrewやpipでインストールできます。エージェントやMCPクライアントでは、llms-install.mdにあるクライアント別のセットアップを利用できます。

🎯 よくある用途

• メール → Markdownアーカイブ — エクスポートした.emlコレクションを、構造化メタデータ付きの読みやすくポータブルなMarkdownに変換します
• RAGおよびLLMへの取り込み — チャンク化やインデックス作成の前に、メッセージ本文、スレッド構造、リンク、添付ファイルのメタデータを正規化します
• エージェントのワークフロー — 変換と診断機能をClaude、Codex、その他のMCPクライアントから直接利用できるようにします
• ナレッジベース — メールをObsidianなどのMarkdownを中心としたシステム、静的アーカイブ、ローカル検索パイプラインに移行します
• デジタル保存 — 特定のメールクライアントに依存せず、人が読めるコンテンツと有用なメッセージ構造を保持します

✨ 特長

• 高精度な変換 — HTMLのサニタイズ、Gmail／Outlookのスレッド分割、インライン画像の処理、カレンダーイベントの要約に対応
• CLI — ファイルまたはディレクトリを指定するだけで実行できます
• ローカルWeb UI — ドラッグ＆ドロップでのインポート、監視モード、変換グレードのバッジ、処理履歴、ジョブごとの診断機能を備えたダークなコマンドセンター風インターフェース
• Inbox／Cabinetのワークフロー — .emlファイルをInboxにドロップすると、dead-letterがMarkdownバンドルをCabinetに整理します
• インストール検証 — dead-letter doctorで実行環境を確認します
• 変換レポート — ファイルごとの診断情報を含む、オプトインのJSONレポートを出力します。自動化や監査向けに、添付ファイルの参照数と保持数も含まれます
• MCP サーバー — Claude Desktop、Claude Code、Codex、その他のMCPクライアントと連携します
• Claudeプラグイン — Claude CodeまたはCoworkにマーケットプレイスからインストールでき、5つのスラッシュコマンド（/dead-letter:convert、/dead-letter:summarize、/dead-letter:triage、/dead-letter:cabinet、/dead-letter:mbox）を利用できます
• ポータブルなエージェントスキル — スキルに対応したエージェントに、.emlファイルをいつ、どのように変換するかを教えます
• Python API — from dead_letter import convertを実行すれば、すぐに使えます

🧠 LLM パイプライン向けに設計

生の .eml ファイルは、下流の LLM および検索パイプラインにとってノイズの多い入力です。MIME ヘッダー、マルチパートの境界、重複した HTML／プレーンテキストの本文、エンコードされた添付ファイルが、すべてテキスト経路に混在します。

dead-letter は、これらを YAML フロントマター付きの Markdown に正規化するため、MIME を解析したり base64 をクリーンアップしたりしなくても、メッセージ本文とメタデータをチャンク化やインデックス作成に利用できます。デフォルトの convert() および convert_dir() の実行では、メッセージごとに単一の .md ファイルが作成され、添付ファイル名はフロントマターに保持されます。

ファイルシステム上の成果物も分けるには、bundle および Cabinet のワークフローを使うと、message.md と、デコード後に保持されたファイルが attachments/ の下に書き出されます。Markdown はテキスト取り込みにすぐ使える状態になり、PDF、スプレッドシート、カレンダーファイル、その他保持されたバイナリ添付ファイルは、すでに利用している下流のパーサーに合わせてきれいに分離されます。

LLM と直接連携するには、MCP サーバーを使うと、クライアントからシェルを介さずに dead-letter の変換ツールを呼び出せます。変換はローカルで行われますが、選択した MCP ホストが、返されたメール本文をリモートモデルに送信する場合があります。

📊 トークンコストのベンチマーク

dead-letter の価値は、あらゆる代替手段よりトークン数が少ないことではなく、トークンあたりの忠実度にあります。生の MIME をコンテキストに持ち込まずに、メールの有用な構造を維持します。HTML スレッド、添付ファイル、ニュースレターを含む11件の合成コーパスを対象に測定しました（トークナイザー o200k_base、構造化スレッドモード）。

• 報告された集計比較では、生の .eml よりトークン数が約88％少なくなっています。添付ファイルカテゴリの中央値は、生データで約126kトークン、変換後は約180トークンです。
• 構造が維持されます。スレッド構造、メッセージごとの送信者情報、リンク、添付ファイルのメタデータは、読み取れる状態で残ります。テストした単純なベースラインは、情報を破棄するため、より低コストになることがよくあります（添付ファイル名の保持数は0/2で、dead-letter は2/2）。

これらの数値は Markdown 表現を測定したものであり、保持されたバイナリ添付ファイルの内容や、下流での回答品質を測定したものではありません。製品版のデフォルトは最新メッセージモードですが、ベンチマークでは同一スレッドで比較するために構造化モードを使用しています。

ベンチマークでは、どのような場合に劣るかも正直に示しています。メタデータ、リンク、スレッド構造を破棄してもよい場合は、単純な抽出のほうがトークン数を減らせます。完全な手法、該当する行を含む全表、トークナイザーの説明、ワンコマンドでの再現方法は benchmarks/ にあります。

📦 インストール

方法を1つ選んでください。配布方法の概要では、各チャネルの位置づけを説明しています。すべてをインストールする必要はありません。

目的	こちらから開始
コア CLI または Python API	下記の Homebrew／pip、または uvx のクイック試用
ローカル Web UI	下記の dead-letter[ui]
Claude Desktop 拡張機能またはその他の MCP クライアント	MCP サーバー
Claude Code／Cowork コマンド	プラグイン
コンテナー分離型 MCP	コンテナー
ポータブルなエージェント向け指示	Agent Skill

Apple silicon 搭載の macOS で Homebrew を使う場合：

brew tap BigCactusLabs/tap
brew install dead-letter

Homebrew の formula は CLI（dead-letter convert、dead-letter doctor）をインストールします。 0.4.7 以降の formula では、dead-letter-mcp サーバーもインストールされます。 オプションの Web UI は含まれません。

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

UI または MCP を分離してインストールするには、pipx を使います。

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

または、グローバルにパッケージをインストールせず、uvx で個別のエントリーポイントを実行します。

uvx --python 3.12 dead-letter convert message.eml
uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp

uv はツールや依存関係をキャッシュし、初回の使用時に Python をダウンロードする場合があります。これらのバージョン未固定の試用コマンドは、実行のたびに最新バージョンが使われることを保証しません。レビュー済みのデプロイについては、バージョンの固定を参照してください。

ソースからインストールする場合：

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

エージェントスキル（任意のホスト）

お使いのエージェントに、ポータブルなエージェントスキルをインストールします。

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

gh 2.90 以降が必要です。このスキルは Claude プラグインとは独立しています。再現性を確保するには、レビュー済みのスキルタグまたはコミットを固定してください。デフォルトの最新リリースがプラグインのリリースである場合もあります。正確な固定構文、その他のホスト、手動インストール、検出メタデータについては、エージェントの検出を参照してください。

🚀 クイックスタート

CLI — 単一ファイルを変換します。

dead-letter convert message.eml

ディレクトリ全体を変換します。

dead-letter convert inbox/ --output out/

出力とともに JSON 変換レポートを生成します。

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

--output を指定すると、レポートはその出力ディレクトリに .dead-letter-report.json として書き込まれます。--output を指定しない場合、ファイル変換ではレポートはソースメッセージと同じ場所に、ディレクトリ変換では入力ディレクトリのルートに書き込まれます。

実行環境を確認します。

dead-letter doctor

ディレクトリ変換では、.eml ファイルを再帰的にスキャンし、サフィックスの大文字と小文字を区別せずに照合します。解決後のターゲットが指定された入力ツリーの外にあるシンボリックリンクファイルはスキップし、同じメッセージファイルに解決されるツリー内のシンボリックリンクの別名は重複排除します。

Web UI — ローカルサーバーを起動します。

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

http://127.0.0.1:8765 を開きます。初回起動時には、デフォルトの Inbox フォルダーと Cabinet フォルダーを提案するセットアッププロンプトが表示されます。インポートまたはジョブの開始前に、これらのフォルダーを設定してください。スキップするとプロンプトは閉じますが、セットアップが完了するまで、これらの操作は引き続き制限されます。ドラッグ＆ドロップまたはファイルピッカーで .eml ファイルをインポートします。単一ファイルのインポートではファイルモードが使用され、複数ファイルのドロップではディレクトリモードのバッチジョブが1つ作成されます。.eml 以外のファイルが混在するドロップでは、それらをスキップする前に確認を求めます。

バックエンドでは、単一およびバッチのアップロードの両方に対して、ファイルごとのインポート上限を 100 MB に設定しています。ブラウザでのバッチには、合計サイズとファイル数の上限もあります。

ソースのチェックアウトから実行する場合は、先頭に 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

オプションを指定する場合：

from dead_letter import convert, ConvertOptions

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

署名画像（ロゴ、ソーシャルアイコン）とトラッキングピクセルを除去します。

result = convert("message.eml", options=ConvertOptions(
    strip_signature_images=True,
    strip_tracking_pixels=True,
))

有効にすると、これらのフィルターはレンダリングされた Markdown から該当する画像を除去し、除去されたインライン署名／トラッキングアセットをバンドルの添付ファイル出力から除外します。

バンドル変換（Markdown、添付ファイル、ソースを1つのディレクトリにまとめます）：

from dead_letter import convert_to_bundle

bundle = convert_to_bundle("message.eml", bundle_root="cabinet/", source_handling="copy")
print(bundle.markdown)     # cabinet/message/message.md
print(bundle.attachments)  # retained extracted files under cabinet/message/attachments/

source_handling="copy" は元の .eml をそのまま保持します。省略した場合、convert_to_bundle() は source_handling="move" をデフォルトとして使用し、ソースメッセージをバンドルに移動します。

保持される抽出済み添付ファイルのファイル名は、attachments/ の下に書き込む前に、安全なベース名に正規化されます。

品質診断には、メッセージに保持対象の添付ファイルがある場合、参照された添付ファイル数と保持された添付ファイル数が含まれます。これにより、破棄された成果物を機械的に検出できます。品質診断を参照してください。

バッチ：

from dead_letter import convert_dir

for r in convert_dir("inbox/", output="out/"):
    print(f"{'✓' if r.success else '✗'} {r.source.name}")

🔌 MCP サーバー

dead-letter にはMCPサーバーが付属しているため、LLM クライアントはシェルコマンドを実行せずに .eml ファイルを直接変換できます。

VS Code、Cursor、Cline：

VS Code にインストール · Cursor にインストール デスクトップクライアントの PATH に uv／uvx が必要です。これらのリンクでは、公開済みの PyPI パッケージを使用するローカルの stdio サーバーを設定します。カタログへの登録は不要です。初回の使用時に、Python と依存関係がダウンロードされる場合があります。承認する前に、コマンド、適用範囲、ツールの権限を確認してください。Cline のセットアップ、手動での JSON の例、検証については、クライアントのインストールを参照してください。

uvx で直接起動します。

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

または、先にインストールします（0.4.7 以降、MCP SDK はコア依存関係です。互換性用の追加機能として [mcp] を引き続き提供します）。

pip install 'dead-letter[mcp]'
dead-letter-mcp

ソースをチェックアウトした場合：

uv run dead-letter-mcp

Claude Desktop（拡張機能バンドル）：

リリースページにある公開済みの package リリース（vX.Y.Z）から、.mcpb ファイルとその .sha256 サイドカーファイルをダウンロードします。プラグインのみのリリースには、このバンドルは含まれません。インストールする前に、ファイルのチェックサムを検証してください。

# macOS: verifies against the downloaded sidecar
shasum -a 256 -c dead-letter-mcp-X.Y.Z.mcpb.sha256

# Windows (PowerShell): compare this hash to the sidecar's hash
certutil -hashfile dead-letter-mcp-X.Y.Z.mcpb SHA256

X.Y.Z を選択した package のバージョンに置き換えてください。互換性のある Claude Desktop ビルドでは、ダウンロードしたバンドルをダブルクリックするか、ウィンドウにドラッグするか、Settings > Extensions > Advanced settings > Install Extension を選択します。拡張機能が接続され、以下のツールが公開されることを確認してから（0.4.5 では 5 つ、0.4.0 以前では convert_mbox はありません）、合成メッセージを変換してください。

このバンドルは、管理対象の uv ランタイムと固定バージョンのパッケージを使用します。初回起動時に、Python と依存関係がダウンロードされる場合があります。チェックサムやコマンドラインでのスモークテストだけでは、使用中のクライアントバージョンで GUI インストールが成功したことの証明にはなりません。MCPB に対応していないホストでは、以下の手動 stdio セットアップを使用してください。

Claude Desktop（手動での claude_desktop_config.json 設定 — 代替方法）：

{
  "mcpServers": {
    "dead-letter": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "dead-letter[mcp]", "dead-letter-mcp"]
    }
  }
}

既存のクライアント設定を置き換えずに、このエントリを統合してください。VS Code などのホストでは異なるスキーマを使用する場合があります。エージェントのインストールガイドを参照してください。

Claude Code または Cowork（推奨 — Claude プラグイン）：

/plugin marketplace add BigCactusLabs/bigcactuslabs-plugins
/plugin install dead-letter

Claude Code 2.1.275 以降では、/plugin install dead-letter --marketplace BigCactusLabs/bigcactuslabs-plugins を実行すると、両方を一度に設定できます。

このプラグインは uvx 経由で MCP サーバーを起動し、5 つのスラッシュコマンドを追加します：/dead-letter:convert、/dead-letter:summarize、/dead-letter:triage、/dead-letter:cabinet、/dead-letter:mbox。ローカルの Claude Code には PATH 上の uv が必要です。ランタイム固有のセットアップと更新については、plugin/を参照してください。メールの内容は指示ではなく、信頼できないデータとして扱われます。埋め込まれたツールの使用、認証情報、データ流出に関する要求には従いません。

マーケットプレイスでは、プラグインのタグとコミットが固定され、ランチャーでは公開済み Python パッケージのバージョンが厳密に固定されます。Claude Code と Cowork では、インストール済みのコピーがそれぞれ別に管理されるため、各クライアントで更新と検証を行ってください。このプラグインには、ロックファイルから起動するホスト向けに、ハッシュ付きの依存関係バージョンを記載した uv.lock も含まれています。通常の uvx は、互換性のある推移的依存関係のバージョンを独自に解決します。

Claude Code（手動での MCP 追加 — 代替方法）：

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

Codex：

codex mcp add dead-letter -- uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp
codex mcp list

mcp list で確認できるのは登録状況であり、ツール呼び出しの成功ではありません。対象のクライアントを通じて接続し、以下のツールが表示されることを確認してから、合成フィクスチャを変換してください。これをもってインストールの検証完了とします。

ツール

ツール	必須の引数	戻り値
convert_eml	eml_path	Markdown テキスト。output_path を指定した場合はファイルも書き込みます。
convert_eml_to_bundle	eml_path, bundle_root	bundle_path、markdown_path、attachment_paths を含む JSON。コピーのみで、元の .eml が移動または削除されることはありません。
convert_directory	directory, output_directory	JSON の概要。1 回の呼び出しにつき .eml ファイルは最大 50 個です。
convert_mbox	path, output_directory	JSON の概要。1 つのフラットな .mbox で、1 回の呼び出しにつき最大 256 MiB、1000 件のメッセージまでです。0.4.5 以降。
get_diagnostics	eml_path	品質と構造に関する JSON。永続的な書き込みは行いません。

5 つすべてで preset（default、clean、verbose、raw）とフラグごとのオーバーライドを指定できます。MCP 固有の制約とエラーテキストの表を含む完全な仕様は、docs/reference/v4-runtime-contracts.md を参照してください。

🗂 プロジェクト構成

src/dead_letter/
├── core/           # conversion pipeline (MIME, HTML, threads, rendering)
├── backend/        # CLI, API server, job runner, watch mode, MCP server
└── frontend/       # static web UI (Alpine.js ES modules + vanilla fetch)
tests/
├── core/           # conversion pipeline tests with .eml fixtures
├── backend/        # API, job, and watch tests
├── plugin/         # plugin, skill, packaging, and release contracts
└── frontend/       # JS unit tests

エージェントガイドでは、README をファイル一覧にすることなく、バンドル、コンテナ、スキル、メンテナー向けツールの構成を説明しています。

🧪 テスト

uv sync --extra dev --locked
uv run pytest -q tests/core        # conversion pipeline
uv run pytest -q tests/backend     # API and job runner
uv run pytest -q tests/plugin      # plugin, skill, packaging, and release contracts
node --test tests/frontend/*.test.js
python scripts/release.py check    # offline distribution metadata

CI では、プラグイン／スキーマ、フロントエンドの構文、メンテナンス対象の Markdown リンク、クロスプラットフォームのパッケージングも検証します。コマンドの全容と、オフラインのコントラクトと実際のクライアントテストの違いについては、貢献ガイドを参照してください。

📚 ドキュメント

• ドキュメントのインデックス — ファイル名ではなく、作業内容に応じて選択してください
• 配布マップ — CLI、UI、MCPB、プラグイン、コンテナ、スキルの選択肢
• エージェントのインストールガイド — クライアントごとのセットアップと検証
• ランタイムコントラクト — API 全体とコア動作の仕様
• フロントエンドの状態モデル
• 品質診断
• 公開 — タグ付け、チャネルの順序、復旧
• ブランド＆スタイルガイド
• 変更履歴
• 貢献ガイド
• エージェントガイド — このリポジトリで作業する AI コーディングエージェント向けの運用ガイド

🔧 おすすめのツール

• MarkEdit — Markdown 用の TextEdit。macOS ネイティブで、約 4 MB です。dead-letter の出力に最初からぴったりだったかのように表示できます。
• mo — ファイルをライブリロード付きでブラウザーに表示するローカル Markdown ビューアーです。Cabinet を指定すれば、変換したメールをフィードのように読めます。

⚠️ 既知の制限事項

• CLI/Python では .eml、フラットな .mbox エクスポート、および（0.4.5 以降）ZIP/TGZ Takeout ダウンロードを受け付けます。Takeout ガイドを参照してください。ウェブ UI は EML のみ対応しています。0.4.5 以降、MCP サーバーには単一のフラットな .mbox 用の上限付き convert_mbox ツールが追加されています。 PST、MSG、およびライブメールボックスへの接続はサポートされていません。 オプトイン方式の再開可能な MBOX インポート（--mbox-resume、CLI/Python のみ）は 0.4.6 以降で利用できます。再開の仕様を参照してください。
• ローカルのみ、単一ユーザー、単一マシン向けです。リモートサーバーや認証サービスはありません。MCP ホストは結果をモデルプロバイダーに送信する場合があります。
• ジョブレジストリはメモリ内にあるため、再起動すると状態がリセットされます。保持されたバイナリー添付ファイルのテキストインデックス作成には、別途パーサーが必要です。

ライセンス

PolyForm Noncommercial 1.0.0 — 個人、教育機関、非営利団体は無料で利用できます。商用利用には、Big Cactus Labsから別途ライセンスを取得する必要があります。