yotta/EmailToDiscord
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d906dc05a9d39a02fab2593a6cce62f3cb1bd918
EmailToDiscord/README.md
T
yotta d906dc05a9
Validate and publish container image / build (pull_request) Successful in 3m24s
Details
Harborプロジェクトをknative-funcに変更
2026-07-18 09:08:04 +09:00

13 KiB
Raw Blame History

Email Notification Forwarder (Discord / Agents Webhook)

メールサーバーを監視し、新しいメールをDiscordへ通知したり、AgentsのWebhookを通じてエージェントを起動したりするPythonアプリケーションです。Discordのみ、Agents Webhookのみ、または両方を同時に利用できます。

🚀 機能

  • メールサーバー監視: IMAP/IMAPS プロトコルでメールサーバーを監視
  • Discord通知: 新しいメールが到着したときにDiscordに通知
  • Agents Webhook通知: メール内容をプロンプトとしてAgentsを起動
  • 複数通知先: DiscordとAgents Webhookへの同時送信に対応
  • 環境変数設定: 設定は全て環境変数で管理
  • Dockerサポート: コンテナとして簡単にデプロイ可能
  • SSL/TLS対応: セキュアな接続をサポート
  • エラーハンドリング: 堅牢なエラー処理とログ出力

📋 必要な環境変数

変数名 説明 必須 デフォルト値
EMAIL_USER メールアドレス ✅ -
EMAIL_PASSWORD メールパスワード/アプリパスワード ✅ -
DISCORD_WEBHOOK_URL Discord Webhook URL 条件付き -
WEBHOOK_URL AgentsのWebhookエンドポイント 条件付き -
WEBHOOK_TOKEN ユーザー単位で発行されたWebhookトークン 条件付き -
DISCORD_CHANNEL_ID エージェントの応答先DiscordチャンネルID 条件付き -
WEBHOOK_SOURCE Agents上で表示するサービス名 ❌ email-monitor
IMAP_SERVER IMAPサーバーアドレス ❌ imap.gmail.com
IMAP_PORT IMAPポート番号 ❌ 993
USE_SSL SSL/TLS使用の有無 ❌ true
MAILBOX 監視するメールボックス ❌ INBOX
CHECK_INTERVAL チェック間隔（秒） ❌ 60

DISCORD_WEBHOOK_URL、またはAgents用の WEBHOOK_URL / WEBHOOK_TOKEN / DISCORD_CHANNEL_ID のいずれか一組が必要です。Agents用の3変数は必ずまとめて設定してください。

🔧 セットアップ

1. Discord Webhook URLの取得（Discordへ直接通知する場合）

  1. Discordでメッセージを送信したいチャンネルを選択
  2. チャンネル設定 → 連携サービス → ウェブフック
  3. 新しいウェブフックを作成してURLをコピー

2. Agents Webhookの設定（Agentsを起動する場合）

Agentsの会話コンテキストに表示される「Webhook エンドポイント（実行時情報）」に従い、現在のユーザー用トークンを取得します。サービスに渡すのは WEBHOOK_TOKEN だけです。マスター鍵である WEBHOOK_SECRET は絶対に設定しないでください。

WEBHOOK_URL=http://agents-host:8080/webhook
WEBHOOK_TOKEN=<user_id>:<hmac>
DISCORD_CHANNEL_ID=123456789012345678
WEBHOOK_SOURCE=email-monitor

メール受信時には、次の形式でAgentsへ送信します。

POST ${WEBHOOK_URL}
Authorization: Bearer ${WEBHOOK_TOKEN}
Content-Type: application/json

{
  "source": "email-monitor",
  "channel_id": 123456789012345678,
  "prompt": "新しいメールを受信しました。..."
}

3. Gmail用アプリパスワードの作成（Gmailを使用する場合）

  1. Googleアカウントの2段階認証を有効にする
  2. Googleアカウント設定 → セキュリティ → アプリパスワード
  3. メール用のアプリパスワードを生成

4. 環境変数の設定

# .env.exampleをコピーして.envファイルを作成
cp .env.example .env

# .envファイルを編集して実際の値を設定

🚢 Agents container_tools へのデプロイ

container_tools はイメージをビルドせず、レジストリからpullして起動します。このリポジトリでは、main へのpush時にGitea Actionsが次のイメージをHarborへ公開します。

harbor.mukan.0am.jp/knative-func/email-to-discord:<commit-sha>
harbor.mukan.0am.jp/knative-func/email-to-discord:latest

1. Gitea Actions Secretsの設定

リポジトリのActions Secretsへ次の2項目を登録します。実際の値をリポジトリやComposeへコミットしないでください。

  • HARBOR_USERNAME
  • HARBOR_PASSWORD

Pull Requestではテストステージと実行イメージのビルドだけを行い、main へマージされたときだけHarborへpushします。

2. デプロイ用Composeの準備

通常の docker-compose.yml は container_tools 用テンプレートです。次の値を実際のデプロイ情報へ置き換えます。

  • イメージタグの latest（可能ならGitea Actionsが公開したコミットSHAへ変更）
  • REPLACE_WITH_EMAIL_USER
  • REPLACE_WITH_EMAIL_PASSWORD
  • REPLACE_WITH_WEBHOOK_URL
  • REPLACE_WITH_WEBHOOK_TOKEN
  • REPLACE_WITH_DISCORD_CHANNEL_ID

Discordへの直接通知も併用する場合だけ、空の DISCORD_WEBHOOK_URL に実際のURLを設定します。WEBHOOK_SECRET は設定しません。

Agentsの実行時情報にある WEBHOOK_URL が http://127.0.0.1:<port>/webhook の場合、コンテナ内の 127.0.0.1 はサテライト自身を指すため、http://host.docker.internal:<port>/webhook に置き換えてください。ComposeにはLinuxからDockerホストへ到達するための host-gateway を設定済みです。

3. デプロイ

置換後のCompose全文を、安定した project_name とともに container_tools へ渡します。デプロイ用Composeには、container_tools が禁止する build、container_name、env_file、host bind mountを含めていません。

🐳 ローカルDocker Composeでの実行

ローカルでソースからビルドする場合は、デプロイ用とは別の docker-compose.local.yml を使用します。

1. .env の設定

EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

# Discordへ直接通知する場合
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL

# Agentsを起動する場合（3項目すべてが必要）
WEBHOOK_URL=http://agents-host:8080/webhook
WEBHOOK_TOKEN=<user_id>:<hmac>
DISCORD_CHANNEL_ID=123456789012345678

2. コンテナの起動

# コンテナをビルドして起動
docker compose -f docker-compose.local.yml up --build -d

# ログの確認
docker compose -f docker-compose.local.yml logs -f

# コンテナの停止
docker compose -f docker-compose.local.yml down

🚀 Linux用シェルスクリプトでの実行

Linux環境では便利なシェルスクリプトを使用できます：

1. スクリプトに実行権限を付与

chmod +x start.sh

2. 初期セットアップ

# .envファイルを作成
./start.sh setup

# .envファイルを編集して実際の値を設定
nano .env

3. よく使用するコマンド

# Dockerイメージをビルド
./start.sh build

# コンテナを起動
./start.sh start

# リアルタイムでログを表示
./start.sh logs-f

# コンテナの状態を確認
./start.sh status

# コンテナを停止
./start.sh stop

# コンテナを再起動
./start.sh restart

# docker-compose で起動
./start.sh compose-up

# Python直接実行
./start.sh python

# ヘルプを表示
./start.sh help

4. 利用可能なコマンド一覧

コマンド 説明
setup 初期セットアップ（.envファイル作成）
build Dockerイメージをビルド
start コンテナを起動
stop コンテナを停止
restart コンテナを再起動
logs ログを表示
logs-f ログをリアルタイム表示
status コンテナの状態を確認
clean 停止済みコンテナとイメージを削除
compose-up docker-compose で起動
compose-down docker-compose で停止
python Python直接実行
help ヘルプを表示

🪟 Windows用PowerShellスクリプトでの実行

Windows環境では PowerShell スクリプトを使用できます：

1. 初期セットアップ

# .envファイルを作成
.\start.ps1 setup

# .envファイルを編集して実際の値を設定
notepad .env

2. よく使用するコマンド

# Dockerイメージをビルド
.\start.ps1 build

# コンテナを起動
.\start.ps1 start

# リアルタイムでログを表示
.\start.ps1 logs-f

# コンテナの状態を確認
.\start.ps1 status

# コンテナを停止
.\start.ps1 stop

# ヘルプを表示
.\start.ps1 help

🔨 Dockerでの直接実行

1. イメージのビルド

docker build -t email-to-discord .

2. コンテナの実行

docker run -d \
  --name email-monitor \
  --restart unless-stopped \
  -e EMAIL_USER=your-email@gmail.com \
  -e EMAIL_PASSWORD=your-app-password \
  -e DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL \
  -e WEBHOOK_URL=http://agents-host:8080/webhook \
  -e WEBHOOK_TOKEN=<user_id>:<hmac> \
  -e DISCORD_CHANNEL_ID=123456789012345678 \
  -e CHECK_INTERVAL=60 \
  email-to-discord

🐍 Python直接実行

1. 依存関係のインストール

pip install -r requirements.txt

2. 環境変数の設定

# Windowsの場合
set EMAIL_USER=your-email@gmail.com
set EMAIL_PASSWORD=your-app-password
set DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL

# Linux/macOSの場合
export EMAIL_USER=your-email@gmail.com
export EMAIL_PASSWORD=your-app-password
export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL

# Agents Webhookを使う場合
export WEBHOOK_URL=http://agents-host:8080/webhook
export WEBHOOK_TOKEN=<user_id>:<hmac>
export DISCORD_CHANNEL_ID=123456789012345678

3. アプリケーションの実行

python app.py

📧 対応メールプロバイダー

Gmail

IMAP_SERVER=imap.gmail.com
IMAP_PORT=993
USE_SSL=true

Outlook/Hotmail

IMAP_SERVER=outlook.office365.com
IMAP_PORT=993
USE_SSL=true

Yahoo Mail

IMAP_SERVER=imap.mail.yahoo.com
IMAP_PORT=993
USE_SSL=true

その他のプロバイダー

各プロバイダーのIMAP設定を確認して適切な値を設定してください。

📊 ログとモニタリング

アプリケーションは以下の情報をログ出力します：

  • 起動/停止メッセージ
  • メールサーバー接続状況
  • 新しいメールの検出
  • Discord・Agents Webhook送信の成功/失敗
  • エラー情報
# Dockerコンテナのログを確認
docker logs email-to-discord-monitor

# リアルタイムでログを監視
docker logs -f email-to-discord-monitor

🔒 セキュリティ考慮事項

  1. アプリパスワードの使用: 通常のパスワードではなくアプリ専用パスワードを使用
  2. 環境変数での機密情報管理: パスワードやWebhook URLは環境変数で管理
  3. SSL/TLS接続: メールサーバーとの通信は暗号化
  4. 非rootユーザー: Dockerコンテナは非rootユーザーで実行
  5. ユーザー単位トークン: Agents連携には WEBHOOK_SECRET ではなく WEBHOOK_TOKEN のみを使用

複数の通知先を設定した場合、すべての通知先への送信が成功してからメールを既読にします。いずれかが失敗したメールは未読のままとなり、次回の監視時に再試行されます。

🛠️ トラブルシューティング

メールサーバーに接続できない場合

  1. IMAP設定が正しいか確認
  2. アプリパスワードが正しく設定されているか確認
  3. 2段階認証が有効になっているか確認（Gmail）
  4. ファイアウォールの設定を確認

Discord通知が送信されない場合

  1. Webhook URLが正しいか確認
  2. Discordサーバーの権限を確認
  3. ネットワーク接続を確認

Agents Webhookが起動しない場合

  1. WEBHOOK_URL が /webhook を含む正しいURLか確認
  2. WEBHOOK_TOKEN が現在のユーザー用に発行された値か確認
  3. DISCORD_CHANNEL_ID が数値のチャンネルIDか確認
  4. Agents側のWebhookエンドポイントへコンテナから接続できるか確認

ログの確認方法

# アプリケーションのログレベルを変更（開発時）
# app.py内のlogging.basicConfig levelをDEBUGに変更

📝 ライセンス

このプロジェクトはMITライセンスの下で公開されています。

🤝 コントリビューション

プルリクエストやイシューの報告を歓迎します。

📞 サポート

問題が発生した場合は、GitHubのIssueにて報告してください。

Reference in New Issue View Git Blame Copy Permalink