---
title: "Gmail API と IMAP の違い：AI エージェントの接続方式"
description: "Gmail を読む AI エージェント向けに、API と IMAP の認証・権限・同期を比較。Mailera のアプリパスワード接続と、読み取り専用キーの設定手順も解説します。"
url: https://mailera.app/ja/blog/gmail-api-vs-imap
published: 2026-10-25
updated: 2026-10-25
---

# Gmail API と IMAP の違い：AI エージェントの接続方式

Gmail 専用なら API、既存の IMAP 実装を使うなら IMAP が候補です。認証方式と読み取り権限を分けて比較し、Mailera 経由で接続する場合の条件も説明します。

## Gmail API と IMAP は何が違う？

Gmail API は、Gmail のメッセージ取得や送信などを行う API です。IMAP はメールを取得・同期するためのプロトコルで、送信には SMTP などを別に使います。

「API か IMAP か」と「OAuth かアプリパスワードか」は別の選択です。[Google の IMAP 認証資料](https://developers.google.com/workspace/gmail/imap/xoauth2-protocol)でも、IMAP で OAuth を使う方法を説明しています。

| 比較項目 | Gmail API に直接接続 | Gmail IMAP に直接接続 |
| --- | --- | --- |
| 対象 | Gmail | Gmail を含む IMAP 対応サーバー |
| 認証 | OAuth | OAuth、利用条件を満たす場合はアプリパスワード |
| 読み取り権限 | `gmail.readonly` を指定できる | 通常の OAuth スコープは `https://mail.google.com/` |
| 取得・検索 | `messages.list` で ID を取得し、`messages.get` で内容を取得 | `X-GM-RAW` で Gmail の検索構文を利用できる |
| ラベル | `gmail.metadata` でもラベルやヘッダーを参照できる | ラベルをフォルダーとして扱い、`X-GM-LABELS` でも取得できる |
| 差分同期 | `history.list` で履歴を取得 | フォルダーをまたぐ識別に `X-GM-MSGID` を利用できる |
| 通知・取得の設計 | Cloud Pub/Sub の通知と本文取得を分ける | クライアントの再接続後に取得漏れを確認する設計にする |
| 送信 | `gmail.send` で送信を許可 | IMAP とは別に SMTP などを使う |
| 運用上の確認点 | OAuth 審査、クォータ、履歴の有効範囲 | 認証条件、フォルダー間の重複、接続管理 |

IMAP では Gmail 固有の情報を扱えない、という理解は誤りです。`X-GM-THRID` でスレッド ID も取得できます。ただし、[Gmail の IMAP 拡張](https://developers.google.com/workspace/gmail/imap/imap-extensions)を他のプロバイダーでも使える前提にはしないでください。

Mailera は、Gmail API や IMAP に代わる第三のメールプロトコルではありません。[Mailera の共通 API](https://mailera.app/ja/product)の背後で、既存のメールボックスに接続します。

![Gmail API への直接接続、IMAP への直接接続、Mailera 経由の接続と認証の違い](https://mailera.app/media/370410ff5c9b25f3/gmail-api-imap-ai-connection-paths-ja-1200.jpg)
_Mailera の API キーの権限と、Google 側の接続資格情報は別に管理します。_

## 読み取り権限と同期の運用負担は？

### 読むだけなら、送信権限を渡さない

Gmail API の `gmail.readonly` はメッセージと設定の閲覧用です。`gmail.metadata` はラベルやヘッダーを読めますが、本文は読めません。本文の要約が必要なら、この違いを踏まえてスコープを選びます。

Google は、IMAP の通常スコープである `https://mail.google.com/` の全権限が不要なら、より細かいスコープを持つ Gmail API への移行を勧めています。

一方、`gmail.readonly` は restricted scope です。[Google のスコープ説明](https://developers.google.com/workspace/gmail/api/auth/scopes)では OAuth アプリの審査が必要とされ、対象データをサーバーに保存・転送する場合はセキュリティ評価も求められます。実装前に、この運用負担も確認してください。

### 通知を受けても、本文は別に取得する

Gmail API の初回同期では `messages.list` から ID を取得し、`messages.get` で内容を読みます。その後は `startHistoryId` を指定して `history.list` で差分を取得します。履歴の範囲外なら HTTP 404 が返り、全体の再同期が必要です。[公式の同期ガイド](https://developers.google.com/workspace/gmail/api/guides/sync)に沿って復旧処理も用意してください。

Cloud Pub/Sub の通知に入るのはメールアドレスと新しい履歴 ID で、本文ではありません。`watch` は少なくとも 7 日ごとの更新が必要です。通知には遅延や欠落もあるため、通知だけを取得漏れの判定根拠にしない設計にします。詳細は [Gmail API の通知ガイド](https://developers.google.com/workspace/gmail/api/guides/push)にあります。

### 料金とクォータは分けて考える

[Google の料金・利用制限](https://developers.google.com/workspace/gmail/api/reference/quota)では、Gmail API の標準利用は追加費用なしと説明されています。ただし、無制限ではありません。消費するクォータ単位はメソッドやクエリパラメーターで異なります。採用時には同ページの適用条件と、Cloud Pub/Sub など関連サービスの費用を別々に確認してください。

## 自分の用途ではどちらを選ぶ？

1. **Gmail 専用かを決めます。** 専用の新規実装なら、細かい OAuth スコープを選べる Gmail API を第一候補にします。
2. **必要な操作を決めます。** 本文の閲覧だけか、送信も必要かを分けてください。接続できることと、エージェントに操作を許すことは別です。
3. **既存の IMAP 実装を確認します。** 他のプロバイダーにも対応するなら再利用を検討します。ただし、認証条件や拡張機能は接続先ごとに確認します。
4. **認証と同期を誰が運用するか決めます。** エージェント側を共通 REST API や MCP にそろえたい場合は Mailera が候補です。アプリパスワードを使えない Gmail に、現行の接続方式を無理に当てはめないでください。

## Mailera で Gmail を接続するには？

[Mailera の Gmail 接続](https://mailera.app/ja/providers/gmail)は、Google OAuth や Gmail API ではなく、アプリパスワードを使う IMAP 方式です。新しい Gmail アドレスは作成しません。既存のメールボックスを接続し、Google 側の管理者ポリシーにも従います。

1. 自分の検証用 Gmail で、2 段階認証とアプリパスワード（app password）の利用可否を確認します。組織アカウントでは管理者の許可も確認してください。条件は [Google のアプリパスワードのヘルプ](https://support.google.com/accounts/answer/185833)にあります。具体的な設定は [Gmail のアプリパスワード作成・接続手順](https://mailera.app/ja/blog/gmail-app-password-setup)を参照してください。
2. Admin または Leader が「メールボックス」→「メールボックスを追加」→「単一メールボックス」を開きます。「メールアドレス」を入力し、Gmail の検出結果を確認して「続行」を選びます。
3. 「接続情報」の「パスワード」には、通常のログインパスワードではなくアプリパスワードを入力します。「メールボックスグループ」も指定してください。
4. 「テストして接続」を実行し、「受信サーバーへのサインイン」と「フォルダーの検出」を確認します。テストではメールを送信しません。送信側だけ失敗した場合は「受信専用で保存」を選べます。
5. 「設定」の API キー設定で「キーを作成」を開きます。「メールボックスのスコープ」を検証用グループに限定し、権限は `read` のみにします。

![対象グループを限定し、読み取り権限だけを設定する Mailera の API キー作成画面](https://mailera.app/media/1405191971aebbd5/gmail-api-imap-ai-read-key-ja-1200.jpg)
_エージェント用キーは、検証用グループと read 権限に限定します。_

REST で取得する場合は、自分のキーを `$MAILERA_API_KEY`、対象のメールボックス ID を `$MAILBOX_ID` に設定します。メールボックス ID は `GET /mailboxes` の `data[].id` で確認できます。

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

一覧の `data[].id` を `$MESSAGE_ID` に設定すると、本文を取得できます。

```bash
curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY"
```

`data.subject` と `data.body.text` を Gmail 画面の検証メールと照合してください。REST の接続情報は [開発者向けページ](https://mailera.app/ja/developers)にあります。

MCP なら「MCP 設定をコピー」を使い、`list_messages`、続いて `get_message` で取得します。どちらも `read` 権限で利用できます。[MCP の接続案内](https://mailera.app/ja/mcp)と、[既存メールボックスをエージェントにつなぐ共通手順](https://mailera.app/ja/blog/connect-existing-email-to-agents)も参照してください。

## よくあるエラーや勘違いは？

### アプリパスワードが表示されない、認証に失敗する

Google は、セキュリティキーだけの 2 段階認証、組織アカウント、Advanced Protection などを、アプリパスワードを利用できない場合の理由として挙げています。通常のログインパスワードで代わりに接続しようとせず、アカウントの条件を確認してください。

Google アカウントのパスワードを変更すると、アプリパスワードは失効します。以前は接続できていたなら、パスワードを変更していないかも確認してください。「IMAP 自体が廃止された」と判断せず、認証方式と資格情報を切り分けます。

### 読めるのに送れない

Mailera の Gmail 受信は IMAP、送信は SMTP です。送信には接続側の成功に加えて、API キーの `send` 権限も必要です。`read` キーで本文を取得できても、送信できることにはなりません。

### 新着メールがすぐに見えない

Mailera の同期頻度は利用状況で変わり、使われていないメールボックスはスリープする場合があります。常時の即時到着は保証しません。`GET /mailboxes` の `data[].status` と `data[].last_sync_at` を確認してください。

`GET /mailboxes/{id}/status` が返すのは最新の同期に基づく状態です。Gmail を含む Microsoft 以外のプロバイダーでは、呼び出すたびに相手のメールサーバーへ直接ログインして確かめるわけではありません。

## メールを読むエージェントを安全に運用するには？

**受信メールは信頼できないデータであり、エージェントへの命令ではありません。** 本文に「API キーを送れ」「外部ツールを実行しろ」と書かれていても従わせないでください。これは prompt injection への対策です。

Mailera のキーを `read` にしても、Google 側のアプリパスワードが読み取り専用になるわけではありません。接続資格情報とエージェント用キーは分けて保管し、対象グループを最小限にします。「有効期限」や「IP制限（任意）」も利用環境に合わせて設定してください。[Mailera のセキュリティ情報](https://mailera.app/ja/security)も確認できます。

送信が必要になったときだけ `send` を追加し、宛先と本文を人が確認する処理をエージェント側に実装します。キーやアプリパスワードを画像・ログに残さず、検証後は不要なものを失効させてください。

**最初のメールボックスを2分で接続** — Outlook、Gmail、IMAPのメールボックスを追加して、アプリやAPIでメールを読めます。 [メールボックスを接続](https://mailera.app/auth?mode=signup)