Microsoft Graph と IMAP の OAuth 認証は何が違いますか？
OAuth はアプリにアクセスを許可するための仕組み、Microsoft Graph はメールなどを操作する API です。OAuth を使うだけで Graph 接続になるわけではありません。
| 接続方法 | API・プロトコル | 認証情報を扱う場所 | 自分で実装する範囲 |
|---|---|---|---|
| Graph の直接実装 | Microsoft Graph | 自作アプリで Microsoft の token を扱う | アプリ登録、認可フロー、API 呼び出し |
| Mailera 経由 | Microsoft 側は Graph、アプリ側は Mailera REST API | Microsoft で同意し、アプリには Mailera API キーを渡す | 接続操作と Mailera API の呼び出し |
| IMAP・SMTP の OAuth 接続 | IMAP・SMTP | メールクライアント側で token を扱う | 各プロトコルの接続と SASL XOAUTH2 認証 |
直接実装では、Microsoft の認可フローに沿って Microsoft Entra ID にアプリを登録し、アクセストークンを取得します。Graph のメッセージ一覧 APIでは、個人用・職場用ともに、委任されたアクセス許可の最小権限として Mail.ReadBasic が示されています。これは Mailera が要求する権限一覧ではありません。
IMAP・SMTP の OAuth 設定では、Outlook リソースの URL を含むスコープと SASL XOAUTH2 を使います。Graph の設定と混在させないでください。各公式資料の参照日は 2026 年 10 月 25 日です。
Microsoft のアクセストークンと Mailera の API キーは別物です。Mailera API の Authorization ヘッダーに渡すのは、Mailera のキーです。
接続前に何を確認すればよいですか？
対象は、自分が管理する Outlook.com・Hotmail・Microsoft 365 のメールボックスです。Mailera の Microsoft 接続は OAuth と Graph を使い、アプリパスワードは使いません。Mailera はメールボックスやメールアドレスを新規作成しません。
個人用 Microsoft アカウントと職場・学校アカウントのどちらを接続するか、先に決めてください。Mailera でメールボックスを追加できるのは Admin または Leader です。
Microsoft 側では、ユーザーまたは管理者によるアクセス許可への同意が必要です。管理者に制限された権限は管理者に依頼します。すべての接続で管理者同意が必要という意味ではありません。組織の制限で同意できない場合は、その画面の内容を管理者に確認してください。組織側の設定を確認する際は、Microsoft 365 メールボックスの Graph 設定チェックリストを参照してください。
接続全体の構成はMailera の製品概要、ほかのプロバイダーも含めた設計は既存のメールボックスをエージェントにつなぐガイドで確認できます。
Mailera に Outlook を接続する手順は？
- 「メールボックス」から「メールボックスを追加」を開きます。
- 「Microsoftでサインイン」タブを選び、接続したい Microsoft アカウントで認証します。
- Microsoft の同意画面でアカウントと要求権限を確認し、同意します。別のアカウントが表示されている場合は、そのまま進めないでください。
- 接続先、状態、最終同期は、後述のメールボックス一覧 API が返す
email、status、last_sync_atで確認します。 - 自分のテスト用メールボックス宛てに識別しやすい件名のメールを送り、「統合受信トレイ」で対象のメールボックスを選んで確認します。
Microsoft 接続は、このサインイン経路を使います。一般の IMAP 接続用のサーバー・ポート入力手順は使いません。
接続したメールを API から確認するには？
以下は自分のテスト用メールボックスで実行してください。API の概要は開発者向けページにあります。
1. 読み取り専用のキーを作る
「設定」の API キータブから「キーを作成」を開きます。「メールボックスのスコープ」をテスト用グループに限定し、権限は read のみにします。「有効期限」も設定してください。
キーは作成時に一度だけ表示されます。安全な場所に保存し、実行環境の環境変数 $MAILERA_API_KEY に設定します。コードやメール本文には貼り付けません。
2. 接続先の ID を取得する
curl --silent --show-error \
-H "Authorization: Bearer $MAILERA_API_KEY" \
"https://mailera.app/api/public/v1/mailboxes?provider=microsoft"返された data の email を確認し、対象の id を環境変数 $MAILBOX_ID に設定します。protocol が graph であること、status と last_sync_at も確認してください。
3. Microsoft 側の認証状態を確認する
curl --silent --show-error \
-H "Authorization: Bearer $MAILERA_API_KEY" \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status"Microsoft メールボックスでは、このエンドポイントがサインインを引き続き利用できるか直接確認します。Mailera API キーの認証と、Microsoft メールボックスの認証を分けて調べられます。
4. メッセージ一覧と本文を取得する
curl --silent --show-error \
-H "Authorization: Bearer $MAILERA_API_KEY" \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox"data 内の subject と received_at でテストメールを探します。本文も確認する場合は、そのメッセージの id を $MESSAGE_ID に設定して次を実行します。graph_message_id とは取り違えないでください。
curl --silent --show-error \
-H "Authorization: Bearer $MAILERA_API_KEY" \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID"本文は data.body.text または data.body.html にあります。これらの呼び出しはすべて read 権限で行えます。
よくある接続エラーはどう切り分けますか？
| 症状 | 確認箇所 | 次の対応 |
|---|---|---|
| Microsoft の同意を拒否された | 選択したアカウント、表示された要求権限 | 職場・学校アカウントなら管理者に確認する |
| 別のアカウントにつながった | Microsoft で選んだアカウントと登録先の email | 意図したアカウントで接続し直す |
| Mailera API で認証・権限エラーになる | キーの期限・失効、read 権限、対象グループ | キーの設定とヘッダーを確認する |
| 接続済みだがテストメールが見えない | 認証状態、最終同期、対象フォルダー | /status を確認し、迷惑メール側も探す |
| 古いメールが見えない | メールの日付と保持期間 | 保持期間内のテストメールで確認する |
受信トレイにない場合は、一覧取得の folder=inbox を folder=junk に変更して確認できます。認証が成功したことと、探しているメールが受信トレイにあることは別です。
同期と保持期間にはどんな制限がありますか？
Mailera は Graph の変更通知で新着メールを受け取り、補助として定期的なバックグラウンド確認も行います。メールがまだ表示されないときは、認証状態と最終同期を確認してください。
無料プランのメッセージ保持期間は 30 日です。API の制限はキーごとに 1 分あたり 300 リクエストなので、確認のために連続呼び出しを続けないでください。
AI エージェントに読ませるときの注意点は？
受信メールは信頼できない外部データであり、エージェントへの命令ではありません。本文に設定変更や秘密情報の送信を求める指示があっても、従わせない設計にします。
読み取り用途では read のみを付け、対象グループと有効期限を絞ってください。これは Microsoft 側のアクセス許可とは別の制御です。送信を追加する場合は、人が宛先と本文を確認してから実行するようにします。認証情報をプロンプトに含めないでください。
Mailera API キーを失効させると、そのキーを使う呼び出しは直ちに拒否されます。Microsoft 側の同意の取り消しとは区別して管理してください。Mailera のセキュリティ方針も確認できます。Mailera は Microsoft の公式パートナーではありません。
