Gmail API と IMAP は何が違う？

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

「API か IMAP か」と「OAuth かアプリパスワードか」は別の選択です。Google の IMAP 認証資料でも、IMAP で OAuth を使う方法を説明しています。

比較項目Gmail API に直接接続Gmail IMAP に直接接続
対象GmailGmail を含む IMAP 対応サーバー
認証OAuthOAuth、利用条件を満たす場合はアプリパスワード
読み取り権限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 拡張を他のプロバイダーでも使える前提にはしないでください。

Mailera は、Gmail API や IMAP に代わる第三のメールプロトコルではありません。Mailera の共通 APIの背後で、既存のメールボックスに接続します。

Gmail API への直接接続、IMAP への直接接続、Mailera 経由の接続と認証の違い
Mailera の API キーの権限と、Google 側の接続資格情報は別に管理します。

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

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

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

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

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

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

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

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

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

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

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

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

Mailera で Gmail を接続するには？

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

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

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

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 に設定すると、本文を取得できます。

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 の接続情報は 開発者向けページにあります。

MCP なら「MCP 設定をコピー」を使い、list_messages、続いて get_message で取得します。どちらも read 権限で利用できます。MCP の接続案内と、既存メールボックスをエージェントにつなぐ共通手順も参照してください。

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

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

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 のセキュリティ情報も確認できます。

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

最初のメールボックスを2分で接続

Outlook、Gmail、IMAPのメールボックスを追加して、アプリやAPIでメールを読めます。

メールボックスを接続