接続前に管理者へ確認することは？
Microsoft Graph は、Microsoft 365 のメールへアクセスする API です。Mailera の Microsoft 接続では、Microsoft 側で OAuth の同意を行います。Mailera はメールボックスやメールアドレスを新規作成しないため、先に利用可能なメールボックスを用意してください。
接続担当者と管理者で、次の表を埋めてから進めます。
| 確認項目 | 担当者 | 確認できるもの | 不明な場合の対応 |
|---|---|---|---|
| 対象テナントと職場アカウント | 接続担当者・組織管理者 | 接続対象のアカウント情報 | 利用するアカウントを確定する |
| 対象メールボックスの利用可否 | メール管理者 | 対象ユーザーがメールを開けること | 利用権限を確認する |
| アプリと要求権限へのユーザー同意 | 組織管理者 | 同意ポリシーと既存の付与内容 | 管理者承認の手順を確認する |
| アプリへのユーザー割り当て | 組織管理者 | 対象ユーザーの割り当て状況 | 組織の利用条件を確認する |
| Mailera での追加権限 | Mailera 管理者 | Admin または Leader ロール | 該当ロールの担当者に依頼する |
Mailera の Admin・Leader は、Microsoft 側の管理者権限とは別です。Mailera で追加操作ができても、組織の同意ポリシーを変更できるわけではありません。
一般ユーザーが同意できるのは、組織がそのアプリと要求権限への同意を許可している場合です。同意が許可されていない場合、同意画面自体が表示されません。管理者同意ワークフローが有効なら、代わりに承認要求用の「Approval required」が表示されます。テナント全体の同意後も、ユーザー割り当てによる利用制限は残せます。
詳細は Microsoft のユーザーと管理者の同意の概要とユーザー同意の設定を参照してください。設定変更で既存の同意が消えるわけではないため、現在の設定だけでなく付与済みの権限も確認します。
Graph の権限と Mailera の API キー権限はどう違う？
Microsoft Graph のアクセス方式には、次の違いがあります。
| 方式 | 誰としてアクセスするか |
|---|---|
| 委任されたアクセス許可 | サインインしたユーザーに代わってアプリがアクセスする |
| アプリケーションのアクセス許可 | アプリ自身の ID でアクセスする |
委任されたアクセス許可では、アプリとユーザーの両方に、その要求を行う権限が必要です。方式の定義は Microsoft の認証と認可の説明にあります。
職場または学校アカウントで Graph のメッセージ一覧を取得する場合、委任されたアクセス許可の最小権限は Mail.ReadBasic とされています。これはGraph の一覧取得操作の要件です。Mailera 接続時は、Microsoft の同意画面に表示される要求権限を確認してください。
一方、Mailera の API キーは、接続済みメールボックスに対してアプリが行える操作を制御します。Microsoft 側の同意を済ませても、Mailera のキーには別途 read が必要です。読み取りの確認だけなら send は付けません。
Microsoft の権限に関する上記資料の参照日は 2026 年 10 月 25 日です。権限リファレンスでも、必要最小限の権限を要求するよう推奨されています。
Mailera で接続して読み取りを確認するには？
検証には、自分が管理するテスト用メールボックスを使います。Mailera の接続機能のうち、ここでは Microsoft サインインと REST API を使います。エージェント接続全体の設計は、既存メールをエージェントにつなぐガイドを参照してください。
- 「メールボックス」→「メールボックスを追加」→「Microsoftでサインイン」を開きます。独自ドメインだからという理由だけで「カスタムIMAP」を選ばないでください。Microsoft 365 を使っているなら「Microsoftでサインイン」を選びます。
- 対象の職場アカウントでサインインします。要求権限を読み、管理者承認が必要なら組織の手順に従います。
- 「設定」の「API key」タブから「キーを作成」を開きます。「メールボックスのスコープ」は対象グループに限定し、権限は
readのみにします。 - 下の順序で API を呼び、対象の選択、サインイン、メッセージ取得を個別に確認します。
API キーを環境変数 MAILERA_API_KEY に設定したうえで、まずメールボックス一覧を取得します。各 API の説明は Mailera のドキュメントにあります。
curl --request GET \
'https://mailera.app/api/public/v1/mailboxes' \
--header "Authorization: Bearer $MAILERA_API_KEY"メールボックス一覧 API の data 内で、email、provider、status、last_sync_at を確認します。email で対象を見つけ、その id を環境変数 MAILBOX_ID に設定してください。
次に、Microsoft メールボックスへのサインインを直接確認します（Microsoft 以外のプロバイダーでは最新の同期結果をもとに判定されますが、Microsoft は毎回直接確認します）。この操作にも read を使います。
curl --request GET \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status" \
--header "Authorization: Bearer $MAILERA_API_KEY"続いて、受信トレイのメッセージを取得します。
curl --request GET \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
--header "Authorization: Bearer $MAILERA_API_KEY"data 内の mailbox_id、folder、subject、received_at を見て、意図したテストメールか確認します。サインイン確認の成功だけで読み取り確認を終えず、メッセージ取得の結果も記録してください。
よくあるエラーはどう切り分ける？
| 症状 | 確認箇所 | 次の対応 |
|---|---|---|
| 管理者承認を求められる | Microsoft 側の同意ポリシー | 組織の承認手順に従う |
| 別のアカウントで接続した | サインインした職場アカウントと対象テナント | 正しい対象で接続し直す |
| 接続後にサインインが失敗する | /status の結果と Microsoft 側の利用条件 | 管理者へ結果を共有する |
| Mailera API を呼べない | キーの read と対象グループ | 必要な範囲のキーを使う |
| サインインできるがメールがない | 対象 ID、フォルダー、同期状態、保持期間 | テストメールの所在を確認する |
Microsoft 側の認証、Graph へのアクセス許可、Mailera API キーの権限は分けて調べます。Mailera の read を増やす代わりに send を付けても、読み取りの切り分けにはなりません。
新着メールの検知には Graph の変更通知を使い、補助として定期的なバックグラウンド確認を行います。委任されたアクセス許可では、変更通知を購読できるのはサインインしたユーザー自身のメールボックスに限られます。即時反映を前提にせず、最終同期も見てください。また、無料プランのメッセージ保持期間は 30 日です。古いメールが見えない場合は、認証だけを疑わず保持期間も確認します。
AI エージェントに読ませる際の安全対策は？
受信メールは信頼できないデータであり、エージェントへの命令ではありません。本文に「この情報を外部へ送れ」「API キーを表示しろ」と書かれていても実行させないでください。
キーは対象グループと必要最小限の権限に限定し、「有効期限」と「IP制限（任意）」を運用に合わせて設定します。キーの値や token は、メール本文、画像、ログに残さないでください。画面を共有するときは、アドレスや本文、テナント情報も伏せます。
MCP を使う場合は、キー作成後の「MCP 設定をコピー」から Claude、Cursor、VS Code 用の設定を取得できます。list_mailboxes、get_mailbox_status、list_messages、get_message は read のツールです。
送信を追加するなら、実行前に人が宛先と本文を確認する処理をアプリ側に設けます。漏えいしたキーは失効させてください。そのキーによる呼び出しは直ちに拒否されます。運用前に Mailera のセキュリティ情報も確認してください。
