Agent Mail Gateway

Agent Mail Gateway

すべてのAIエージェントに、それぞれ専用のメールアドレスを与えましょう。メールボックスの鍵を渡す必要はありません。

Agent Mail Gatewayは、既存のメールサーバー上にある通常のメールボックスとAIエージェントの間に配置する、小規模なセルフホスト可能サービス（Dockerコンテナ1つ）です。各エージェントには、1つのメールボックス専用のAPIキーが発行されます。ゲートウェイを通じてメールの閲覧や返信、添付ファイルの送信、カレンダー招待の管理ができます。ただし、許可した相手とのやり取りに限られ、送信されるすべてのメッセージは送信前にチェックされます。

エージェントはMCP（Model Context Protocol）またはシンプルなREST APIを通じて接続します。メールはHTMLではなくMarkdownで届くため、トークンを大幅に節約できます。

---

その理由

エージェントにメールボックスのIMAP/SMTPパスワードを渡すと、すべてのメールを読み、誰にでもメールを書けるようになります。また、受信メールに含まれたプロンプトインジェクション1つで、データの漏えいや迷惑メールの送信を引き起こす可能性があります。ゲートウェイはパスワードを保持し、リクエストごとにルールを適用します。

ゲートウェイを使わない場合	ゲートウェイを使う場合
エージェントがメールボックスのパスワードを知っている	エージェントが持つのは、そのメールボックス専用のAPIキーのみ
迷惑メールやフィッシングを含むすべてのメールを読む	許可した送信者からのメールのみを閲覧
誰にでもメールを書ける	許可した宛先にのみメールを書ける
不注意なメールや誤ったメールが送信される	送信前にすべてのメールをチェック（ルール、オプションのLLM、ユーザーのポリシー）
マルウェアやプロンプトインジェクションがエージェントに届く	添付ファイルと本文は受信時にチェックされ、非表示またはフラグ付けされる
HTMLメールで数千トークンを消費	メールは簡潔なMarkdownで届く

機能

メールボックスへのアクセス

• メールの一覧表示、検索、閲覧、フラグ設定、削除に対応します。添付ファイルの送受信はテキスト、Base64、または受信メッセージから直接行えるため、エージェントがCSVのBase64を扱う必要はありません。
• PDFや画像をエージェント向けにテキストとして取得できます（get_attachmentでformat: "text"を指定）。PDFのテキストレイヤーに標準対応し、画像はビジョンモデルまたはローカルOCR（Tesseract）で処理します。
• 返信（全員に返信を含む）と転送に対応します。ゲートウェイが宛先、「Re:」／「Fwd:」、スレッド処理を補います。
• HTMLからMarkdownへの変換（閲覧用）と、MarkdownからHTMLへの変換（送信用）に対応します。

カレンダー

• 招待の送信、更新、キャンセルに対応し、Outlook、Gmail、Apple Calendarで正しく反映されます。
• 招待を承諾または辞退した人を確認できます。
• 受信した招待を読み取り、承諾、辞退、または仮承諾できます。

制御と安全性

• メールボックスごとに、エージェントがメールを受信できる送信者とメールを送信できる宛先の許可リストを設定できます（name@domainまたは*@domain）。それ以外はエージェントから見えず、ゴミ箱に移動されます（または保持されます）。
• 偽装された送信者は拒否されます（メールサーバーが確認するSPF／DKIM／DMARCに基づきます）。
• 受信メールの添付ファイルと内容をチェックできます。それぞれ非表示、フラグ設定、無効を選択でき、送信者ごとにスキップできます。危険なファイル（プログラム、マクロ、偽装されたファイル形式。デフォルトで有効）、ClamAVによるウイルススキャン、テキスト、PDF、画像のプロンプトインジェクションチェックに対応します（詳細は以下を参照）。
• 1時間あたりの送信上限と、送信、拒否、削除すべての監査ログを備えています。
• パスワードが間違っている場合に素早く再試行しないため、サーバーのfail2banがゲートウェイをブロックすることはありません。

送信前の確認（詳細は以下を参照）

• 標準搭載のルールで、空のメール、添付ファイルのみのメール、添付ファイルがないのに「添付をご覧ください」と書かれたメール、プレースホルダーの残り、意図しない重複を検出します。デフォルトで有効です。
• 「このメールに不足はなく、内容も妥当か」を確認する任意のLLMレビューに対応します（例：Ollamaのローカルモデル）。
• 任意のポリシーに対応します。全員または特定の宛先に適用する、平易な言葉で記述した独自ルールです。例：「財務情報は決して共有しない」、「Alexに贈り物のことを決して話さない」。

連携

• Streamable HTTPによるMCP、stdioのみ対応するクライアント向けのstdioブリッジ、OpenAPIドキュメントを/docsで提供するREST APIに対応します。
• 新着メールの署名付きWebhookに対応します（Hermes AgentのWebhookルートと互換性があります）。
• エージェントにメールボックスの使い方を教えるスキルを備えたHermes Agentプラグインを提供します。
• Plesk、IONOS、Outlook、Postfix/Dovecotなど、あらゆるIMAP/SMTPサーバーで動作します。

仕組み

 Agent ──MCP / REST + API key──▶ ┌────────────────────────────────────────┐
                                 │ Auth       key → exactly one mailbox   │
 Agent ◀──signed webhook──────── │ Policy     who may write / be written  │
                                 │ Review     rules · LLM · your policies │
                                 │ Inbound    file types · virus · inject.│
                                 │ Converter  HTML ⇄ Markdown             │
                                 │ Calendar   invitations and replies     │
                                 │ Mailbox    IMAP + instant new-mail push│──IMAP──▶ your mail server
                                 │ Sender     SMTP + copy to "Sent"       │──SMTP──▶
                                 └────────────────────────────────────────┘
                                   config.yaml + .env (read-only)

メールはメールサーバー上に保持されます。ゲートウェイが保存するのは、独自の状態を記録した小さなSQLiteファイルのみです。

クイックスタート

エージェントごとに専用のメールボックスを使用してください（例：[email protected]）。個人用のメールボックスは使用しないでください。デフォルトでは、許可リストにない送信者からのメールはゴミ箱に移動されます。

1. ファイルを取得します。

   mkdir agent-mail-gateway && cd agent-mail-gateway
   curl -LO https://raw.githubusercontent.com/dominikamann/agent-mail-gateway/main/docker-compose.yml
   curl -L -o config.yaml https://raw.githubusercontent.com/dominikamann/agent-mail-gateway/main/config.example.yaml
   curl -L -o .env https://raw.githubusercontent.com/dominikamann/agent-mail-gateway/main/.env.example
   

2. config.yamlを編集します。各エージェントについて、メールサーバー、ログイン情報、許可リストを設定します。
3. シークレットを.envに記述します（openssl rand -hex 32で適切なAPIキーを生成できます）。
4. 起動して確認します。

   docker compose up -d
   curl http://localhost:8080/health   # {"status":"ok"}; with a key also that mailbox's state
   curl -H "Authorization: Bearer <the AGENT_API_KEY from .env>" http://localhost:8080/v1/mailbox
   

最小構成のメールボックスエントリー：

mailboxes:
  - name: assistant
    address: [email protected]
    api_key: ${AGENT_API_KEY}
    imap: { host: mail.yourmailserver.eu, port: 993, security: tls }
    smtp: { host: mail.yourmailserver.eu, port: 465, security: tls }
    username: [email protected]
    password: ${AGENT_MAIL_PASSWORD}
    allow_receive_from: [[email protected], "*@yourcompany.eu"]
    allow_send_to: [[email protected]]

すべてのオプションについてはdocs/configuration.mdで説明しています。

送信前のレビュー

エージェントが不注意なこともあります。添付ファイルだけのメール、「添付をご確認ください」と書いてあるのにファイルがないメール、Hello {name} などです。ゲートウェイは、送信されるすべてのメールと招待を送信前にチェックします。問題がある場合は何も送信されず、エージェントには理由を示す明確なエラー（review_rejected）が返されるため、メッセージを修正して再試行できます。拒否された試行は送信上限にカウントされません。

チェックは3つのレイヤーで構成され、メールボックスごとに選択できます。

レイヤー	デフォルト	内容
ルール	オン（block）	AIを使わない固定チェックです。本文が空、添付ファイルのみ、件名がない、添付ファイルへの言及があるのにファイルがない、プレースホルダーが残っている、10分以内に同じメールを送信している、過去の日付の招待などをチェックします。
LLMレビュー	オフ	言語モデルに、メッセージが完成していて筋が通っているかを確認させます（例：返信が質問に実際に答えているか）。
ポリシー	オフ	自然言語で記述した独自のルールを、言語モデルでチェックします。すべての受信者、または特定の受信者のみに適用できます。

ルールとLLMレビューでは、メッセージをブロックするか、警告のみを出す（送信は行い、結果を報告する）か、オフにするかを選べます。各ポリシールールでは、ブロックするか警告するかを選べます。チェック対象は、新規メール、返信、転送、招待とその変更、および招待への回答に含まれるコメントです。

    review:
      rules: block                       # block | warn | off
      llm:                               # any OpenAI-compatible endpoint, e.g. a local Ollama
        url: http://ollama:11434/v1
        model: llama3.1:8b
        mode: warn                       # quality check: warn | block | off
      policies:
        mode: block                      # what a violation does: block | warn
        rules:
          - rule: Never share financial information such as revenue, prices, invoices, bank details or salaries.
          - rule: Never mention gifts, presents or surprise plans.
            recipients: [[email protected]]
          - rule: Never send calendar invitations.
            recipients: [[email protected]]

ポリシーでは添付ファイルも読み取ります。テキストファイル、PDF、そして attachments.read_images が設定されている場合は画像も対象です。recipients を指定したルールは、その受信者のいずれかがメッセージを受け取る場合（To、Cc、Bcc、または招待の参加者）にのみ適用されます。Ollama を使えば、レビューはすべて自分のマシン上で実行され、メールの内容がサーバーの外部に送信されることはありません。長いメッセージは分割してチェックされるため、途中で切り捨てられることはありません。分割サイズと上限は、使用するモデルのコンテキストウィンドウに合わせて設定できます。組み込みのレビュープロンプトは、置き換えたり拡張したりできます。詳しくはdocs/configuration.mdをご覧ください。

受信メールのチェック

許可リストは、エージェントに連絡できる「人」を決めます。これらのチェックでは、届いた「内容」を確認します。各チェックで、検出時の動作を選べます。メッセージを非表示にする（許可されていない送信者と同様に扱う）、フラグを付ける（エージェントには警告付きで表示し、危険なファイルはダウンロードできないようにする）、またはオフにする、のいずれかです。skip_senders を使うと、信頼できる送信者にはチェックを適用しません。これにより、メールでエージェントに指示を送ることができます。

チェック	デフォルト	内容
dangerous_attachment	flag	プログラムやスクリプト（ファイル名と内容で判定）、マクロを含む Office ファイル、偽装ファイル（PDFではない invoice.pdf など）、プログラムを含む ZIP、パスワードで保護されたアーカイブをチェックします。送信ファイルにも適用されます。
virus	hide	すべての添付ファイルを ClamAV でスキャンします（任意のコンテナ）。送信ファイルも対象です。
prompt_injection	flag	review.llm のモデルで、テキスト、PDF、画像にAIを対象とした指示が含まれていないかをチェックします。
scan_failed	flag	スキャナーまたはモデルに接続できず、チェックを実行できなかった場合に適用されます。

    attachments:
      clamav: { host: clamav, port: 3310 }          # optional, see docker-compose.yml
      read_images: { engine: ocr, languages: [eng, deu] }   # or a vision model
    inbound_checks:
      prompt_injection:
        action: flag
        skip_senders: [[email protected]]       # your own instructions are not flagged
      dangerous_attachment: { action: hide }

画像はビジョンモデル（Ollama の qwen2.5vl など）か、ゲートウェイ内のOCR（Tesseract）で読み取ります。PDFには pdf.js を使用します。必要であれば、すべてを自分のマシン上で実行できます。詳しくはdocs/configuration.mdをご覧ください。

使用方法

MCP ツール

Authorization: Bearer <api key> ヘッダーを指定して、任意の MCP クライアントから http://<host>:8080/mcp に接続するか、stdio ブリッジを使用してください。

ツール	機能
get_mailbox_info	自分のアドレス、現在の日付と時刻、許可リスト、制限、確認ルール／ポリシーを取得します
list_messages	受信メールを新しい順に一覧表示します。未読で絞り込むか、テキスト、送信者、件名、日付で検索できます
read_message	添付ファイル一覧と受信した招待を含む、1 件のメッセージを Markdown 形式で表示します
get_attachment	添付ファイルをダウンロードするか、PDF／画像をテキストとして読み取ります（format: "text"）
mark_message / delete_message	既読／未読に設定します。許可されている場合はゴミ箱に移動します
send_message	新しいメールを送信します（Markdown、添付ファイル）
reply_message / forward_message	スレッド内で返信（全員に返信）するか、添付ファイル付きで転送します
create_event / update_event / cancel_event	招待を送信、変更、キャンセルします
list_events / get_event	参加者の返信状況を含む、自分のイベントを取得します
respond_to_invitation	受信した招待を承諾、辞退、または仮承諾します

REST

# send a message
curl -X POST http://localhost:8080/v1/messages \
  -H "Authorization: Bearer $AGENT_API_KEY" -H "Content-Type: application/json" \
  -d '{"to":["[email protected]"],"subject":"Daily report","body_markdown":"All **green** today."}'

# unread mail
curl -H "Authorization: Bearer $AGENT_API_KEY" "http://localhost:8080/v1/messages?unread=true"

すべてのエンドポイント、エラーコード、Webhook 形式については、docs/api.md をご覧ください。

Hermes Agent

MCP サーバーを ~/.hermes/config.yaml で接続し、エージェントがメールボックスを安全に利用する方法を教えるプラグインをインストールしてください。

hermes plugins install dominikamann/agent-mail-gateway/integrations/hermes/agent-mail-gateway --enable

新着メールを受信したときにエージェントを起動する方法を含む手順については、docs/hermes.md をご覧ください。

ドキュメント

• 設定 — すべてのオプション、許可リスト、確認、ポート、送信者認証
• REST API、Webhook、MCP ツール
• Hermes Agent の統合とプラグイン
• stdio クライアント
• セキュリティモデル
• コントリビューション · 変更履歴

セキュリティ

ゲートウェイはプライベートネットワーク上、または TLS を使用するリバースプロキシの背後で実行してください。API キーは Authorization ヘッダーで送信されます。SECURITY.md の説明に従って、脆弱性を非公開で報告してください。

ライセンス

MIT

---

amannlabs.eu より誇りを込めて提供