メールをサードパーティのサーバーに送信しないローカルGmailクリーナー

いつか私たちは皆、メールを開くと数万件の未読メッセージに遭遇します。5年前に何かを購入した店舗からの割引情報や、サービスダイジェスト、タスクトラッカーの通知など。Gmail標準のインターフェースでこれらの整理を手動で行うのは、Googleのウェブクライアントが一度に50〜100件以上の選択をなかなか処理してくれないため、悪夢のような作業になります。

ほとんどの商用メールクリーンアップツールは、サブスクリプション形式で動作します。アカウントへのフルアクセスを要求し、メールを自有のサーバーに送信して分析します。gmail-cleanerプロジェクトの作者は異なるアプローチを取りました：公式Gmail APIを通じてローカルマシンでのみ動作する、軽量なツールとウェブインターフェースを作成しました。

なぜローカルでクリーンアップするのか

このプロジェクトの主なアイデアは、完全なプライバシーです。サードパーティのバックエンド、外部データベース、有料プランは一切ありません。スタック全体がローカルで動作し、データが外部に送信されることはありません。

このアプリケーションは4つの一般的な問題を解決します：

• ニュースレターを見つけ、ワンクリックで購読解除を支援します。
• 送信者ごとにメールをグループ化し、どの送信者が受信トレイを最も混乱させているかを示します。
• 選択した受信者からのスレッドを一括削除またはアーカイブします。
• 数千件のメールを数秒で既読としてマークします。

削除されたメールはすべてGmailの標準ゴミ箱に移動されます。誤って必要なものを削除してしまった場合でも、Googleの標準ウェブインターフェースから30日間データを復元できます。

高速化のため、このユーティリティはGmail APIのバッチリクエストを使用し、最大100件のオペレーションを1回の呼び出しにパックします。これにより、数千件のメールのクリーンアップが最小限の時間で完了します。

内部構造と動作原理

内部使用的是Python 3.9+と、Gmail自身のスタイルでクリーンなインターフェースを提供するウェブサーバーです。

セキュリティの観点から、Google Cloud Consoleで自有のアプリケーションを作成します。これにより、OAuthトークンはユーザーにのみ属し、必要な最小限の権限のみがリクエストされます：メールをゴミ箱に移動し既読状態を変更するための読み取り・変更アクセス。

ファイルcredentials.jsonとtoken.jsonはローカルに保存されます。Dockerビルドでは、この目的のために別個のボリューム./dataが提供されるため、コンテナの再起動後に再認証する必要がありません。

プロジェクトのデプロイ方法

プロジェクトを実行する最も簡単な方法はDocker経由です。仮想環境愛好家のために、uvパッケージマネージャーを使用したオプションもあります。

まず、Google Cloud Consoleに移動し、プロジェクトを作成し、Gmail APIを有効化し、OAuthクライアントIDを生成します（Docker用はWebアプリケーションタイプ、直接Python実行用はデスクトップアプリ）。OAuth同意画面でテストユーザーリストに自分のメールを追加することを忘れないでください。

ダウンロードしたファイルをプロジェクトルートにcredentials.jsonとして保存します。

Dockerでの実行

リポジトリをクローンします：

git clone https://github.com/Gururagavendra/gmail-cleaner.git
cd gmail-cleaner

credentials.jsonファイルをその横に配置し、コンテナを起動します：

docker compose pull && docker compose up

次にブラウザでhttp://localhost:8766を開き、サインインボタンをクリックし、コンテナログからGoogle認証リンクを取得してアクセスを許可します。

Pythonとuvでの実行

Dockerを設定したくない場合は、uvで直接スクリプトを実行できます：

uv sync
uv run python main.py

インターフェースは同じアドレスhttp://localhost:8766で利用可能になります。

フィルターとデータエクスポート

単純なクリーンアップを超えて、このプロジェクトには高度なフィルターが含まれています。添付ファイルのサイズ、日付範囲、または標準のGmailカテゴリ（プロモ션、ソーシャル、アップデート、フォーラム、プライマリ）でメールをソートできます。

古いビジネスメールの削除前に送信者と日付に関する情報を保存する必要がある場合、インターフェースはメタデータをCSVにエクスポートできます。

誰が役立つのか

このプロジェクトは、受信トレイが50,000件を超え、Google Driveの無料ストレージ上限に近づいている人に最適です。

確かに、初期設定にはGoogle Cloud ConsoleとOAuthキーの作成に5〜10分の作業が必要です。しかし、見返りとして、メールをサードパーティのサーバーで読み取ることも、基本的なクリーンアップ機能に月額サブスクリプションを要求することもないツールが手に入ります。