mcpField
E
email-imap-full-fetch

email-imap-full-fetch

github.com/tiangong-ai生産性1191 回インストール1 週間前に更新
リポジトリ

email-imap-full-fetch について

Email IMAP Full Fetchは、IMAPメールボックスから指定メールを取得し、解析済みの内容と添付ファイルのメタデータを返すスキルです。Message-Idでの完全一致を優先し、UIDにフォールバックして、元メールと添付ファイルをローカルに保存します。

主な機能

  1. 01Message-Id検索とUIDフォールバック
  2. 02完全なraw MIMEの取得
  3. 03ヘッダー、テキスト本文、HTML本文の返却
  4. 04.emlファイルと添付ファイルの保存
  5. 05冪等な記録と安全なファイル名処理

活用シーン

  1. 01ルーティング済みメールの取得と処理
  2. 02本文と添付ファイルのメタデータ抽出
  3. 03重複記録を避けたメールとファイルの保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/tiangong-ai/agent-skills --skill email-imap-full-fetch

インストール後、Claude Code で/email-imap-full-fetchを入力して読み込まれたか確認します。

詳細

メールのIMAP完全取得

主な目的

  • IMAPから安定したメッセージ参照情報を使って対象のメールを1件取得します。
  • 検索順序を徹底します。まずHEADER Message-Idで完全一致を検索し、次にuidをフォールバックとして使います。
  • BODY.PEEK[]を使ってMIMEデータ全体をダウンロードします。
  • ヘッダー、本文全体、HTML本文、添付ファイルのメタデータを解析して返します。
  • ファイル名の安全性とインデックスの冪等性を確保しながら、.emlファイルと添付ファイルをディスクに保存します。

標準フロー

  1. 入力には、ステージ1のルーティング出力（mail_ref.message_id_norm）から取得したmessage_id_normを含める必要があります。
  2. デフォルトの方法として、fetch --message-id "<message_id_norm or raw Message-Id>"を使います。
  3. 使用可能なメッセージIDがない場合に限り、fetch --uid "<uid>"を使います。
  4. メールボックスの選択はステージ1と一致させます（--mailboxまたはIMAP_MAILBOX）。
  5. JSON出力を読み取り、返されたmail_refを使って後続の処理を続けます。

コマンド

Message-Idで取得（優先）：

python3 scripts/imap_full_fetch.py fetch --message-id "<[email protected]>"

UIDで取得（フォールバック時のみ）：

python3 scripts/imap_full_fetch.py fetch --uid "123456"

必要に応じて両方を使う（先にMessage-Idで検索し、次にuidでフォールバック）：

python3 scripts/imap_full_fetch.py fetch --message-id "<[email protected]>" --uid "123456"

出力仕様

  • 出力は単一のJSONオブジェクトです。
  • 必須のトップレベルフィールド：
    • mail_ref
    • headers
    • text_plain
    • text_html
    • attachments
    • saved_eml_path
  • mail_refには以下が含まれます：
    • account、mailbox、uid、message_id_raw、message_id_norm、date
  • attachments[]には、ファイルごとのメタデータと保存結果が含まれます：
    • filename、content_type、bytes、disposition、saved_path、skipped_reason

保存と冪等性

  • saved_eml_pathは、BODY.PEEK[]から取得して保存したローカルの.emlファイルを示します。
  • 添付ファイルのバイナリデータはJSONに含めず、添付ファイル自体を保存します。
  • ファイル名からパス区切り文字と安全でない文字を取り除きます。
  • 添付ファイル名が重複する場合は、コンテンツハッシュのサフィックスを付けて重複を解消します。
  • message_id_normインデックスを使うことで、リクエストを繰り返しても冪等に処理され、既存の永続化済みJSONレコードがそのまま返されます。

パラメーター

  • --message-id：優先する検索キーです。
  • --uid：フォールバック用の検索キーです。
  • --mailbox：検索するメールボックスです（デフォルトはIMAP_MAILBOXまたはINBOX）。
  • --save-eml-dir：.emlファイルの保存先ディレクトリです（環境変数IMAP_FULL_SAVE_EML_DIR）。
  • --index-dir：冪等性インデックスJSONファイルの保存先ディレクトリです（環境変数IMAP_FULL_INDEX_DIR、デフォルトは<save-eml-dir>/.index）。
  • --save-attachments-dir：添付ファイルの保存先ディレクトリです（環境変数IMAP_FULL_SAVE_ATTACHMENTS_DIR）。
  • --max-attachment-bytes：保存する添付ファイルの最大サイズです（環境変数IMAP_FULL_MAX_ATTACHMENT_BYTES）。
  • --allow-ext：許可する添付ファイルの拡張子です。カンマ区切りで指定します（環境変数IMAP_FULL_ALLOW_EXT）。
  • --connect-timeout：IMAP接続のタイムアウト秒数です（デフォルトはIMAP_CONNECT_TIMEOUTから取得）。

必須の環境変数

  • IMAP_HOST
  • IMAP_USERNAME
  • IMAP_PASSWORD

アカウントのデフォルト設定（任意）：

  • IMAP_NAME
  • IMAP_PORT
  • IMAP_SSL
  • IMAP_MAILBOX

スクリプト

  • scripts/imap_full_fetch.py

コメント

Markdown 対応