email-imap-fetch

Email IMAP Fetch

主な目的

• IMAP IDLE を使って新着メールを待機します。
• 起動するたびに未読メッセージを取得します。
• env で設定した複数のメールボックスアカウントに対応します。
• 実行時の判定は行わず、env のモード（idle または poll）で IDLE のサポートを厳密に制御します。
• 取得した各メールを OpenClaw Webhook に転送します。
• 後続のステップで使える、機械可読な JSON 行を出力します。
• このスキルはステージ 1 のルーティングモードに厳密に限定します。スニペットと構造化参照のみを送信し、メッセージ本文全体や添付ファイルのバイナリデータ／内容は決して送信しません。

ワークフロー

1. アカウントの env 変数と OpenClaw Webhook の env 変数を設定します（references/env.md と assets/config.example.env を参照）。
2. 設定を検証します。

python3 scripts/imap_idle_fetch.py check-config

3. アカウントごとに IDLE サイクルを 1 回実行します（スモークテスト）。

python3 scripts/imap_idle_fetch.py listen --cycles 1 --idle-seconds 120 --max-messages 10

4. 継続して実行します（デフォルトの常駐モード）。

python3 scripts/imap_idle_fetch.py listen

ランタイムモデル

• スキルファイルはローカルにインストールされますが、リスナーは自動起動しません。
• idle モードでは、リスナープロセスと IMAP 接続が稼働している間のみ、IMAP IDLE でプッシュイベントを受信します。
• poll モードでは、リスナーはポーリング間隔の間スリープし、その後、未読メッセージを取得します。
• プロセスが終了するとプッシュイベントを受信できませんが、次回の実行時に UNSEEN で既存の未読メールを取得できます。
• デフォルトのランタイムは常駐モードです（デフォルトでは IMAP_CYCLES=0）。
• デフォルトの IDLE モードは poll です（IDLE をサポートしていないサーバーでも安全です）。
• 本番環境では、常時稼働のデプロイを systemd、launchd、supervisor、または同等のデーモンマネージャーで実行してください。
• 対話型の exec セッションにひも付いたフォアグラウンドプロセスとしてリスナーを実行しないでください。そのセッションが終了すると、リスナーも停止します。

出力仕様

• 出力形式は JSONL です（1 行につき JSON オブジェクト 1 つ）。
• ライフサイクルイベントには type=status を使用します。
• 取得したメールには type=message を使用し、以下を含めます。
  • account、mailbox、seq、uid
  • subject、from、to、date
  • message_id_raw、message_id_norm（および互換性フィールドの message_id）
  • snippet（プレーンテキストのプレビューのみ）
  • attachment_count、attachment_manifest（要約のみ。添付ファイルの内容は含みません）
  • mail_ref 機械可読オブジェクト（account、mailbox、uid、message_id_raw、message_id_norm、date）
• Webhook メッセージには、確定的なディスパッチ抽出のため、以下の 2 つの固定された機械可読ブロックを含めます。
  • <<<MAIL_REF_JSON>>> ... <<<END_MAIL_REF_JSON>>>
  • <<<ATTACHMENT_MANIFEST_JSON>>> ... <<<END_ATTACHMENT_MANIFEST_JSON>>>
• サイクルのステータス出力において、wait_mode は idle または poll です。
• wait_events には、アクティブな待機方式の詳細を記録します。
• OpenClaw Webhook の POST が成功すると、event=webhook_delivered のステータスイベントを出力します。
• アカウント単位のエラーには type=error を使用します。
• OpenClaw Webhook の POST が失敗すると、event=webhook_failed のエラーイベントを出力します。

パラメーター

• --cycles：アカウントごとの IDLE サイクル数（0 は無制限）。
• --idle-seconds：各 IDLE 呼び出しの最大待機時間。
• --poll-seconds：ポーリングモードが有効な場合に使用する間隔。
• --idle-mode：idle または poll。
• --max-messages：各サイクルで取得する未読メールの最大数。
• --mark-seen / --no-mark-seen：未読状態の更新を制御します。
• --snippet-chars：プレビューの文字数制限。
• --connect-timeout：接続タイムアウトの秒数。
• --retry-seconds：失敗後の再試行間隔。

環境変数のデフォルト値：

• IMAP_CYCLES
• IMAP_IDLE_MODE
• IMAP_IDLE_SECONDS
• IMAP_POLL_SECONDS
• IMAP_MAX_MESSAGES
• IMAP_MARK_SEEN
• IMAP_SNIPPET_CHARS
• IMAP_CONNECT_TIMEOUT
• IMAP_RETRY_SECONDS

OpenClaw Webhook 転送：

• OPENCLAW_WEBHOOKS_ENABLED
• OPENCLAW_WEBHOOKS_TOKEN
• OPENCLAW_WEBHOOKS_BASE_URL
• OPENCLAW_WEBHOOKS_MODE（agent または wake）
• OPENCLAW_WEBHOOKS_ENDPOINT（任意のエンドポイント上書き）
• OPENCLAW_WEBHOOKS_PATH
• OPENCLAW_WEBHOOKS_WAKE_MODE
• OPENCLAW_WEBHOOKS_DELIVER
• OPENCLAW_WEBHOOKS_TIMEOUT
• OPENCLAW_WEBHOOKS_NAME
• OPENCLAW_WEBHOOKS_AGENT_ID
• OPENCLAW_WEBHOOKS_CHANNEL
• OPENCLAW_WEBHOOKS_TO
• OPENCLAW_WEBHOOKS_MODEL
• OPENCLAW_WEBHOOKS_THINKING
• OPENCLAW_WEBHOOKS_AGENT_TIMEOUT_SECONDS
• OPENCLAW_WEBHOOKS_SESSION_KEY_PREFIX

エラー処理

• 環境変数の設定が無効な場合、コード 2 で終了します。
• idle モードで IDLE がサポートされていない場合、明示的なエラーを返し、IMAP_IDLE_MODE=poll を提案します。
• 実行時エラーは type=error として出力されます。
• アカウントの処理中にエラーが発生した場合、コマンドはゼロ以外のコードで終了します。

参考資料

• references/env.md

アセット

• assets/config.example.env

スクリプト

• scripts/imap_idle_fetch.py