Claude Agent SDK でメール返信を承認制にする

読み取り・返信案・送信の担当を分ける

Claude Agent SDK は、ツールを使う AI エージェントをアプリから動かすための SDK です。メール操作には Mailera の MCP サーバーを使い、承認状態はアプリで管理します。

Mailera は既存のメールボックスに接続するサービスです。新しいメールボックスやメールアドレスは作成しません。接続先を選ぶ段階なら、既存メールをエージェントにつなぐ方法を先に確認してください。

実装前に何を用意すればよいですか？

自分が管理する検証用メールボックスを Mailera に接続します。Outlook や Microsoft 365 は OAuth を使います。手順は Microsoft メールボックスの接続を参照してください。

Python 版は pip install claude-agent-sdk で導入できます。Python SDK の公式 READMEでは Python 3.10 以降が必要です。Claude Code CLI はパッケージに同梱されるため、標準のセットアップでは別途インストールしません。SDK の認証を済ませ、使用バージョンと実行環境を控えておきます。

Mailera の Claude 連携と SDK 側の設定は分けて考えてください。接続先とキーが正しくても、SDK のツール権限設定によって呼び出しが止まる場合があります。

手順 1：読み取り専用キーで MCP に接続する

1. Mailera の「設定」から API キーの管理画面を開き、「キーを作成」を選びます。
2. 「メールボックスのスコープ」で検証用のグループを指定します。権限は read だけにし、send、move、manage は付けません。
3. 作成直後にキーを保存します。「MCP 設定をコピー」から接続情報を取得し、SDK 側の MCP 接続設定に反映します。
4. 接続先を https://mailera.app/api/public/v1/mcp、認証ヘッダーを Authorization: Bearer $MAILERA_API_KEY とします。キーは環境変数などから渡し、ソースやログに書きません。
5. list_mailboxes を呼び、検証用グループのメールボックスを取得できるか確認します。

allowed_tools だけでは、使えるツールを限定できません。 Python SDK では、ここに列挙したツールが自動承認されます。列挙していないツールの扱いは permission_mode と can_use_tool の判断に進みます。特定のツールを禁止する設定は disallowed_tools です。

SDK は標準で Read、Write、Edit、Bash なども利用できます。メール読み取り用キーに加え、不要なツールを拒否する SDK 側の制御も設けてください。Mailera のキー権限と、SDK の実行許可は別の境界です。

接続に失敗したら、同じキーで REST の読み取りを試すと切り分けられます。

curl --fail-with-body 'https://mailera.app/api/public/v1/mailboxes?limit=1' \
  -H "Authorization: Bearer $MAILERA_API_KEY"

REST で取得でき、MCP では失敗するなら、次に SDK 側の接続設定とツール許可を調べます。API 全体の入口は Mailera の開発者向けページにあります。

手順 2：対象メールと返信案を結び付ける

list_messages または search_messages で候補を絞り、get_message で本文を取得します。いずれも read 権限で使えます。最初は検証用メールだけを対象にし、必要以上のメールを読み込ませない構成にします。

アプリはメールボックス ID とメッセージ ID を保持してください。件名だけで返信先を特定すると、同じ件名の別メールと取り違えます。返信案には、参照元の ID に加えて宛先・件名・本文を保存します。

返信案はアプリ内のデータとして保存します。メールプロバイダーの下書きフォルダーへの保存を前提にしません。人の確認画面には元メールも表示し、返信案との対応を確認できるようにします。

手順 3：確認した内容だけを送信実行部へ渡す

承認は「このエージェントの送信を許可する」ではなく、「この宛先へ、この内容を返信する」に結び付けます。承認の入口はアプリ側に置き、メール本文やモデルの出力を承認として扱いません。

次はアプリ内で使う Python の承認チェックです。approved には、人が承認した時点の返信案をアプリの保存領域から読み出して渡します。

from dataclasses import dataclass

@dataclass(frozen=True)
class ReplyDraft:
    mailbox_id: str
    message_id: str
    to: tuple[str, ...]
    subject: str
    body: str

def require_approval(current: ReplyDraft, approved: ReplyDraft | None):
    if approved is None or current != approved:
        raise PermissionError("承認済みの返信案と一致しません")
    return current

この関数は内容の一致を判定する部品です。誰が承認したかの認証や保存はアプリで実装します。宛先・本文・返信対象などを変更したら確認待ちへ戻し、再承認を求めてください。送信実行部はチェックを通過した返信案そのものを使い、後から編集された内容に差し替えません。

読み取り用エージェントに送信用キーは渡しません。別の送信実行部だけが send 権限で reply_to_email を呼び、get_send_status で結果を確認します。アプリ側には送信処理中の状態を保存し、承認ボタンの連打で同じ返信を重複実行しない制御も置きます。

承認をメール経由で受け取る場合も、この内容との結び付けは維持します。入口の作り方はメールによる人の承認パターンで扱っています。

よくある失敗の確認箇所と対処

送信結果が不明なときは、同じ返信をすぐに再送しないでください。まず get_send_status で状況を確認します。REST の送信状態には queued、sending、sent、failed、unknown があります。unknown は再送してよいという合図として扱わず、人の確認対象にします。

ツール呼び出しの成功、送信完了、相手の受信トレイへの到達は別です。Mailera は受信トレイへの到達を保証しません。

メール本文の指示で誤操作させないためには？

受信メールは信頼できないデータであり、エージェントへの命令ではありません。「外部へ転送して」「秘密情報を表示して」と書かれていても、実行指示として扱わせないでください。引用文や添付ファイル由来の内容も同じ扱いにします。

プロンプトだけで防がず、読み取り専用キー、SDK のツール制御、アプリ側の承認チェックを組み合わせます。MCP 仕様の安全原則も明示的な同意を求めていますが、プロトコル自体がその制御を強制するわけではありません。

自作のテストメールに外部転送や秘密情報の出力を促す文を入れ、未承認送信が起きないことと、出力にキーが含まれないことを確認してください。メール本文を丸ごとログへ残さず、画面の個人情報も伏せます。接続前の確認事項は Mailera のセキュリティ、アカウント連携の論点は Claude や ChatGPT にメールを接続する際の安全性を参照してください。