---
title: "Claude Agent SDK でメール返信を承認制にする"
description: "Claude Agent SDK と Mailera MCP で既存メールを読み、返信案を人が確認してから送信する設計。read 権限、Python の承認チェック、結果不明時の対処を解説します。"
url: https://mailera.app/ja/blog/claude-agent-sdk-email-approval
published: 2026-10-25
updated: 2026-10-25
---

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

Mailera MCP で既存のメールを読み、返信案はアプリに保存します。Python 側の承認チェックと送信処理を分け、却下や本文変更で送信を止める構成を示します。

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

Claude Agent SDK は、ツールを使う AI エージェントをアプリから動かすための SDK です。メール操作には [Mailera の MCP サーバー](https://mailera.app/ja/mcp)を使い、承認状態はアプリで管理します。

| 担当 | 役割 | 渡す権限 |
| --- | --- | --- |
| SDK の読み取り実行部 | 対象メールを取得し、返信案を作る | Mailera の `read` |
| アプリ | 返信案を保存し、人の承認を記録する | 送信用キーは不要 |
| 送信実行部 | 承認済みの内容だけを返信する | Mailera の `send` |

Mailera は既存のメールボックスに接続するサービスです。新しいメールボックスやメールアドレスは作成しません。接続先を選ぶ段階なら、[既存メールをエージェントにつなぐ方法](https://mailera.app/ja/blog/connect-existing-email-to-agents)を先に確認してください。

![Mailera MCP で読む SDK 実行部から返信案を作り、人の確認後だけ別の送信実行部へ進む構成](https://mailera.app/media/f71099d3a91e80d5/claude-agent-sdk-approval-boundary-ja-1200.jpg)
_返信案の保存と承認はアプリの担当です。送信用キーは読み取り用エージェントから分離します。_

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

自分が管理する検証用メールボックスを Mailera に接続します。Outlook や Microsoft 365 は OAuth を使います。手順は [Microsoft メールボックスの接続](https://mailera.app/ja/providers/microsoft)を参照してください。

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

[Mailera の Claude 連携](https://mailera.app/ja/integrations/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` を呼び、検証用グループのメールボックスを取得できるか確認します。

![検証用グループと読み取り権限に限定した Mailera の API キー設定](https://mailera.app/media/7587b1dbc43c942b/claude-agent-sdk-read-key-ja-1200.jpg)
_読み取り用のキーには送信権限を付けません。コピーした設定に含まれるキーも秘密情報として扱います。_

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

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

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

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

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

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

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

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

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

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

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

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

```python
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` で結果を確認します。アプリ側には送信処理中の状態を保存し、承認ボタンの連打で同じ返信を重複実行しない制御も置きます。

| 入力・操作 | 確認する動作 |
| --- | --- |
| 返信案を却下 | 送信ツールを呼ばない |
| 承認後に本文を編集 | 承認を無効にし、再確認を求める |
| 別メールの ID に変更 | 承認チェックで止める |
| 同じ承認を再度送信要求 | 既存の送信処理を確認する |

承認をメール経由で受け取る場合も、この内容との結び付けは維持します。入口の作り方は[メールによる人の承認パターン](https://mailera.app/ja/blog/ai-agent-email-approval)で扱っています。

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

| 症状 | 確認箇所と対処 |
| --- | --- |
| MCP に接続できない | URL、認証ヘッダー、キーの有効性を確認し、REST の読み取りと切り分けます。 |
| 対象メールボックスが出ない | キーに指定したグループと、メールボックスの所属を確認します。 |
| ツールを呼べない | SDK 側の許可判断と Mailera 側のスコープを別々に調べます。 |
| メールが見つからない | 対象メールボックス、フォルダー、検索条件、接続状態を確認します。`sync_mailbox` には `sync` 権限が必要です。 |
| 返信できない | `send` 権限とメールボックスの送信可否を確認します。受信専用の接続では送信できません。 |

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

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

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

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

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

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

**MCPでAIエージェントがメールボックスを利用** — MaileraのMCPサーバーをClaude、Cursor、VS Codeに追加すると、エージェントがメールの閲覧、分類、返信を行えます。 [MCPの使い方を見る](https://mailera.app/ja/docs#mcp)