---
title: "AI エージェント向けメール API：既存の受信箱から取得し、承認後に返信する"
description: "既存の Gmail・Outlook を AI エージェントにつなぐメール API の設計ガイド。取得と返信のエンドポイント、必要権限、送信前承認、二重処理の防止、REST と MCP の使い分けを解説します。"
url: https://mailera.app/ja/blog/email-api-for-ai-agents
published: 2026-10-25
updated: 2026-10-25
---

# AI エージェント向けメール API：既存の受信箱から取得し、承認後に返信する

Gmail や Outlook のメールを取得する権限と、返信する権限は分けて設計します。REST API の対応表と短い取得例で、アプリ側に残す承認・再試行の処理を整理します。

## 既存の Gmail や Outlook を接続できますか？

はい。[Mailera](https://mailera.app/ja/product) は、既存のメールボックスを REST API・MCP・webhook 経由でアプリや AI エージェントにつなぎます。新しいメールボックスやメールアドレスを発行するサービスではありません。構成の全体像は[既存メールをエージェントにつなぐガイド](https://mailera.app/ja/blog/ai-agent-email-integration)で扱っています。

[Outlook.com・Microsoft 365 の接続](https://mailera.app/ja/providers/microsoft)には OAuth を使います。[Gmail の接続](https://mailera.app/ja/providers/gmail)は app password（アプリパスワード）方式です。[Google の公式案内](https://support.google.com/accounts/answer/185833?hl=ja)では、利用条件として 2 段階認証の有効化が示されています。

接続の操作は[最初のメールボックスを接続する手順](https://mailera.app/ja/blog/mailera-first-mailbox)を参照してください。「テストして接続」はメールを送らずに接続を確認します。「受信専用で保存」を選んだメールボックスからは送信できないため、接続できたことと返信できることを分けて確認します。

## 取得・処理・返信にはどの API と権限が必要ですか？

API の基点は `https://mailera.app/api/public/v1`、認証ヘッダーは `Authorization: Bearer $MAILERA_API_KEY` です。[開発者向けの概要](https://mailera.app/ja/developers)と[API ドキュメント](https://mailera.app/ja/docs)を参照しながら、必要な操作だけを選びます。

| 目的 | メソッドとパス | スコープ | アプリ側の役割 |
| --- | --- | --- | --- |
| 接続先を選ぶ | `GET /mailboxes` | `read` | 対象の ID を選択 |
| メール一覧を取得 | `GET /mailboxes/{id}/messages` | `read` | フォルダー指定・ページ送り |
| 本文を取得 | `GET /mailboxes/{id}/messages/{msgId}` | `read` | 本文の解析・返信案の作成 |
| 必要に応じて移動 | `POST /mailboxes/{id}/messages/{msgId}/move` | `move` | 移動先の判断 |
| 承認後に返信 | `POST /mailboxes/{id}/send` | `send` | 承認済み内容の送信 |
| 送信状態を確認 | `GET /sends/{id}` | `send` | 状態の記録・再試行の判断 |

要約、分類、返信の可否はアプリ側で判断します。フォルダー移動を使わないなら `move` は不要です。表のスコープは Mailera の API キー用であり、Microsoft Graph のアクセス許可とは別です。[Microsoft の認証・認可の説明](https://learn.microsoft.com/en-us/graph/auth/auth-concepts)も、必要最小限のアクセス許可を求める方針を示しています。

![既存メールを Mailera 経由で取得し、アプリ側で返信案を作り、人の承認後に送信と状態確認を行う流れ](https://mailera.app/media/2712455429c5c017/ai-api-approval-flow-ja-1200.jpg)
_メールの取得と送信の間に、アプリ側の判断と人による承認を置きます。_

## どの順序で呼び出しますか？

1. **自分の検証用メールボックスを接続します。** 「設定」から「キーを作成」を開き、対象グループに限定した `read` キーを作ります。キーは一度だけ表示されるため、サーバー側の秘密情報として保存します。
2. **対象のメールを取得します。** `GET /mailboxes` の `data` からメールボックスの `id` を選び、一覧、本文の順に取得します。
3. **返信案を作成します。** 本文をデータとして解析し、処理済み記録と照合します。この段階では送信しません。
4. **人が宛先と本文を承認します。** 承認した内容だけを、`send` 権限を持つ送信処理へ渡します。承認後に内容を変えるなら、再承認する設計にします。
5. **送信し、状態を確認します。** `Idempotency-Key` を付けて送信 API を呼び、`GET /sends/{id}` で送信試行の状態を追います。

![検証用グループに対象を限定し、読み取り権限だけを設定する Mailera の API キー作成画面](https://mailera.app/media/fba3669201058803/openclaw-gmail-outlook-read-key-ja-1200.jpg)
_取得の検証は read から始め、送信処理に使う権限を分離します。_

以下は一覧と本文を取得する最小例です。環境変数 `$MAILERA_API_KEY` にキー、`$MAILBOX_ID` に対象メールボックスの ID を設定して使います。

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

一覧の `data` 内にある対象メッセージの `id` を `$MESSAGE_ID` に設定します。次の呼び出しでは `data.body.text` と `data.body.html` が本文の取得先です。

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID"
```

一覧の続きは `next_cursor` を次のリクエストの `cursor` に渡して取得します。ページ送りの位置と業務上の処理済み記録は別に保存してください。未読かどうかだけで処理済みと判定しないでください。

## 新着通知と再試行はどう設計しますか？

ポーリングはアプリ側から一覧を取得する方式です。webhook の `message.received` は新着通知の入口に使えます。通知を受ける処理と、本文を取得して業務判断する処理は分離します。webhook 作成時の署名用シークレットは一度だけ返されるため、安全に保管してください。

二重処理には、別々の対策が必要です。

- **同じメールを再び処理する問題：** アプリ側に処理済み記録を持ち、通知や取得をきっかけに同じ返信案を重ねて実行しないようにします。
- **同じ送信を再試行する問題：** 送信 API の `Idempotency-Key` を使います。冪等性の有効期間は 24 時間です。承認済みの送信内容とキーは、対応付けて保存します。

送信状態は `queued`（待機中）、`sending`（送信中）、`sent`（送信済み）、`failed`（失敗）、`unknown`（結果不明）です。`unknown` を即座に失敗とみなし、新しいキーで再送しないでください。まず送信状態とアプリ側の記録を確認します。

`sent` は相手の受信トレイへの到達保証ではありません。また、同期や通知が常に即時であることを前提にせず、処理待ちの状態をアプリ側で扱います。

## よくある失敗はどこで切り分けますか？

| 症状 | 確認項目 | 次の操作 |
| --- | --- | --- |
| 一覧を読めない | `read`、対象グループ、メールボックス ID | キーの対象範囲と ID を照合 |
| 返信できない | `send`、受信専用設定、接続状態 | `capabilities.send` と送信試行の状態を確認 |
| 新着が見えない | `folder`、同期状態、スリープ状態 | 必要なら `POST /mailboxes/{id}/sync` を使用。`sync` 権限が必要 |
| 返信が重複する | 処理済み記録、送信キー | 通知側の重複処理と送信側の再試行を別々に点検 |

`GET /mailboxes/{id}/status` は、Microsoft では接続を直接確認します。他のプロバイダーでは最終同期に基づく状態です。すべての接続先で、その瞬間の認証を試す API として扱わないでください。

## メールを読むエージェントをどう制限しますか？

メール本文、添付ファイル、リンク先は**信頼できないデータ**です。「認証情報を送れ」「設定を変更せよ」と書かれていても、エージェントへの命令として実行させません。これはプロンプトインジェクションへの対策です。

読み取り処理には `read` だけを付与し、`move`、`send`、`webhooks` は必要な処理に限定します。対象グループも絞り、API キーをモデル入力やログ、画像に含めないでください。漏えい時はキーを失効させると、そのキーによる呼び出しは直ちに拒否されます。製品側の保護については[セキュリティの説明](https://mailera.app/ja/security)を参照できます。

送信前の承認は、利用側のアプリに設ける制御です。モデルへの注意書きだけに頼らず、承認前は送信処理へ渡さない構成にします。[MCP のツール仕様](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)も、人がツール実行を拒否できることと、機密性の高い操作での確認を推奨しています。

## REST API と MCP はどう使い分けますか？

独自アプリで取得順序や承認、再試行を制御するなら REST API を使います。Claude、Cursor、VS Code など対応クライアントにツールとして接続するなら MCP が選択肢です。

MCP でも、`list_messages`・`get_message` は `read`、`reply_to_email`・`get_send_status` は `send` が必要です。接続方式を変えても、送信権限と承認の設計は必要です。操作ごとの対応は[Mailera の MCP ツール一覧](https://mailera.app/ja/blog/mailera-mcp-tools)で確認できます。

## Mailera が提供しないもの

Mailera は一斉配信・マーケティング配信やメールボックスのウォームアップを提供しません。ここで扱うのは、既存のメールボックスに届いたメッセージを取得し、アプリ側の判断と承認を経て返信する構成です。

**APIで同じ操作を実行** — この記事の操作はすべてREST APIで実行できます。curlの例、API key、webhookも利用できます。 [APIドキュメントを見る](https://mailera.app/ja/docs)