Skip to content

Version 1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@prgtake prgtake released this 17 Jul 15:41
v1.0.0
f77257b

スマートメール一括送信システム (Gemini AI搭載)

Excelの宛先リストを元に、Gemini AIを用いて個別の送付ファイル（PDF、Word、Excel等）を自動的に紐付けし、件名や本文を差し替えてメール（Outlook / Gmail）を一括生成・送信するデスクトップアプリケーションです。

主な機能

  • 安全な資格情報管理 (keyring ＆ OAuth2 連携)
    • GmailのアプリパスワードやGemini APIキーを settings.json などの設定ファイルに平文で保存せず、OSの安全な資格情報マネージャー（Windows Credential Manager 等）に暗号化保存します。
    • 新Outlookにおいては、パスワード不要でMicrosoft公式ブラウザログイン経由の先進認証（OAuth2 / MSAL）によるセキュアな接続に対応しています。
  • Gemini AI による高度な添付ファイル自動紐付け
    • ファイル名部分一致に加え、ファイル名から宛先を推測する「Geminiファイル名判定」、ファイルの中身（テキスト）を読み取って宛先を推測する「Gemini中身判定」の3大ルールを搭載。
    • 起動時に前回のマッチング結果を自動復元するキャッシュ機能を搭載し、Gemini APIキーの重複消費を防ぎます。
  • 送信処理の劇的な高速化
    • 送信開始時にサーバーとの接続セッションを確立して最後まで再利用するため、メール1通ごとにログインを繰り返す無駄な通信待ち時間を排除しました。
    • 共通添付ファイルのBase64エンコード（計算負荷の高い処理）やディスク確認をループ外で1回のみ事前に行うキャッシュ機構により、処理速度が従来比で数倍〜数十倍に向上しています。
  • 紐付け結果の高度なExcel出力
    • 送信前の紐付け結果プレビュー一覧を、ワンクリックで専用Excelとして出力できます。
    • 多重添付は「赤文字」、添付なし（未設定）は「黄色背景」で自動色分けされ、問題のあるセルをクリックすると 「その個別フォルダが直接エクスプローラーで起動する」 ハイパーリンクが自動で埋め込まれます。
  • リトライ＆バックオフによるエラー耐性
    • Gemini APIのレート制限（429エラー）やサーバー一時エラー（5xx）に遭遇した場合、指数バックオフで最大3回まで自動リトライします。
  • 「Gemini無料枠利用」チェックボックス機能 (自動レートリミッター)
    • 無料枠 (15 RPM) を利用する際に、API制限（429エラー）を回避するため、リクエスト間隔を自動で調整（1分間に12回、最低5.0秒間隔のウェイトを自動挿入）してゆっくり安全に処理します。
  • リアルタイム進行状況表示
    • 時間がかかるGeminiの中身判定処理中も、何件中何件目を判定しているかがUIボタン上にリアルタイム表示されます。
  • 送信前プレビュー＆ダブルクリック手動修正
    • AIが紐付けた結果を一覧表で確認でき、未紐付けや誤紐付けの箇所はダブルクリックすることでエクスプローラから手動でファイルを選択し直せます。
  • 多機能な送信結果エビデンス（Excel）の自動出力
    • 送信完了後、送信ログシート（送信ステータス・添付ファイル名一覧など、重複は赤文字表示）に加え、「元の宛先リストのコピー」 および 「送信した本文テンプレート（折り返し表示）」 を別シートとして1つのExcelファイル内に自動パッケージ保存します。

前提条件

  • OS: Windows 10 / 11 (推奨)
  • Python: Python 3.10 以上
  • APIキー: Gemini API キー (環境変数 GEMINI_API_KEY またはアプリ画面からの入力で設定)

セットアップ手順

  1. リポジトリの配置
    任意のフォルダに本システムを展開します。

  2. 依存パッケージのインストール
    コマンドプロンプトまたはPowerShellを開き、以下のコマンドを実行します。

    pip install -r requirements.txt

  3. 環境変数の設定 (任意)
    Gemini API キーを設定します。（※アプリ画面から入力して保存することも可能です）

    • コマンドプロンプトの場合: 
      setx GEMINI_API_KEY "あなたのAPIキー"
    • PowerShellの場合: 
      [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'あなたのAPIキー', 'User')

起動方法

1. スクリプトから起動する場合

以下のコマンドを実行してアプリケーションを起動します。

python app.py

2. EXE（アプリ）化して起動する場合

同梱されている build.bat をダブルクリックするだけで、自動的に依存関係のインストールと PyInstaller によるビルドが行われ、dist/SmartBulkMailer.exe（コンソール非表示の単一実行ファイル）が生成されます。

ディレクトリ構成

  • app.py : メインUIアプリケーション（CustomTkinter実装）
  • matching_engine.py : ファイル紐付け・メール生成・送信エンジン（Outlook COM / SMTP / IMAP連携）
  • build.bat : Windows環境でワンクリックでアプリ（EXE）化するためのビルドスクリプト
  • settings.json : 保存された設定（パスワードやAPIキーは暗号化されてOS資格情報マネージャーに保存されます）
  • token_cache.json : 新Outlook（OAuth2）のサインイントークンキャッシュ
  • matching_results_cache.json : 紐付け結果の自動復元用キャッシュ
  • requirements.txt : 依存パッケージ一覧
  • 使用マニュアル.md : 一般ユーザー向けの詳しい操作説明書

Smart Bulk Mailer (Gemini AI Powered) - README (English)

A desktop application designed to dynamically map individual attachment files to recipients from an Excel list using Gemini AI, replace templates with personalized data, and execute bulk email transfers securely and rapidly via Outlook or Gmail.

Key Features

  • Secure Credentials (keyring & OAuth2)
    • Stores Gmail app passwords and Gemini API keys in the OS secure credential manager instead of plaintext inside settings.
    • Supports modern OAuth2 / MSAL authentication for New Outlook, utilizing secure browser login without entering passwords.
  • Advanced File Mapping via Gemini AI
    • Features Substring matching, AI-powered filename matching, and AI-powered content analysis that parses text within files.
    • Automatically restores previous matching results on startup via cash files to prevent redundant Gemini API usage.
    • "Gemini無料枠利用" (Gemini Free Tier Usage) Checkbox: Paces API request intervals (12 RPM, minimum 5.0s between requests) when checked, enabling stable execution under Gemini Free Tier limits without facing 429 Rate Limit errors.
  • High-Speed Execution
    • Reuses SMTP/IMAP connections during batch transfers to eliminate login overhead for each email.
    • Caches Base64 encoding of common attachments to decrease CPU/I/O load, boosting overall speed by up to dozens of times.
  • Advanced Excel Export of Mappings
    • Exports matching results to Excel with duplicates highlighted in red and missing files in yellow.
    • Generates clickable local folder hyperlinks (file:///) for error cells, opening the specific directory directly in Windows Explorer.
  • Detailed Send Logs (Excel)
    • Saves evidence spreadsheet packages with 3 sheets: "Send Status Logs" (duplicates colored red), "Original Recipients Copy", and "Send Body Template".

Prerequisites

  • OS: Windows 10 / 11 (Recommended)
  • Python: Python 3.10+
  • API Key: Gemini API Key (configurable via environment variable or app UI)

Running the Application

1. Run from Script

python app.py

2. Package into EXE

Double-click build.bat to automatically verify dependencies and build a standalone executable dist/SmartBulkMailer.exe (window-only, console hidden).

Assets 3
Loading