Microsoft 365 Outlook API
完全ガイド

Outlookは、会社のメールを読むソフトです。ブラウザでは Outlook on the web、Macではメールアプリからも開けます。中にあるメールそのものは、あなたのMacの中ではなく、会社のMicrosoft 365にあります。

Microsoft 365は、Outlook、予定表、ファイルなどをまとめた会社向けのサービスです。メールアドレスが 名前@会社のドメイン の形なら、それは会社のアカウントです。

Microsoft Graphは、その会社のサービスへプログラムから届く、Microsoft公式の窓口です。メールを読むときも、この窓口を使います。古いOutlook REST APIという別の窓口は、新しく作るアプリでは使いません。

APIを使うと何ができるか

この教科書で作るのは、次の1つだけです。サインインした本人の受信トレイから、件名と受信日時を最大10件、自分のWebアプリの画面に表示します。

• できること: 本人のプロフィール確認、受信トレイの件名と受信日時の表示。
• この初期設定ではできないこと: メールの送信、削除、既読への変更、他人のメールを見ること。

APIキーとアクセストークンの違い

街中の説明で「APIキーを発行する」と書かれていても、Outlookのメール読み取りはAPIキー方式ではありません。

パスワードをWebアプリに保存してOutlookへ入る方法は使いません。あなたはMicrosoftのログイン画面でサインインし、Webアプリはあとから通行証だけを受け取ります。

認証と、メール取得の通信方向

一般の社員がアプリを登録できないとき

会社は「Users can register applications（ユーザーはアプリケーションを登録できる）」を無効にできます。場所は Entra ID、ユーザー、ユーザー設定です。無効なら、新規登録が失敗します。その場合は作業を止め、クラウド アプリケーション管理者かアプリケーション開発者ロールを持つ人に登録を依頼します。

Microsoft 365の契約と、Azureの課金

確認日の公式一覧で、呼び出し回数に応じてAzureへ課金されるGraph APIは、SharePointとOneDriveの assignSensitivityLabel です。メールの /me と /me/mailFolders/inbox/messages はこの一覧にありません。TeamsのAPIは2025年8月25日から従量課金の対象外になっています。

開くページは https://entra.microsoft.com/ です。アプリの登録は、プログラムをMicrosoftへアップロードする作業ではありません。会社の名簿に「このWebアプリが、あとでサインインを依頼してよい」と記録する作業です。

テナントIDが概要に見当たらないときは、Entra ID のトップの概要にも同じ「ディレクトリ (テナント) ID」があります。ラベルの文字が一致する方をコピーします。

リダイレクトURIをWebとして登録する

クライアント シークレットが必要になる条件

保存先のファイルは、まだ中身がプレースホルダの見本です。本物の値への差し替えは、第8章でアプリ用フォルダを作ったあと、あなた自身が行います。

CLOUD_INSTANCE=https://login.microsoftonline.com/
TENANT_ID=00000000-0000-0000-0000-000000000000
CLIENT_ID=00000000-0000-0000-0000-000000000000
CLIENT_SECRET=replace-with-the-secret-value
REDIRECT_URI=http://localhost:3000/auth/redirect
POST_LOGOUT_REDIRECT_URI=http://localhost:3000/
GRAPH_API_ENDPOINT=https://graph.microsoft.com/
EXPRESS_SESSION_SECRET=replace-with-a-long-random-string

CLOUD_INSTANCE と GRAPH_API_ENDPOINT の末尾の / は残します。消すと、テナントIDの直前で住所がつながります。EXPRESS_SESSION_SECRET は、シークレットとは別の、自分で作った長いランダム文字列です。

初期構成は、委任されたアクセス許可です。アプリが自分の権限で全員のメールを読む方式ではありません。サインインした本人の範囲だけです。

最小権限に合わせ、件名と受信日時だけを読む許可を選びます。確認日の「メッセージ一覧」の公式ページでは、仕事用アカウントで最も小さい委任の許可は Mail.ReadBasic です。Mail.Read は本文も読める、ひとつ強い許可です。

権限一覧の「管理者の同意が必要」列は、User.Read、Mail.ReadBasic、Mail.Read の委任では No です。ただし会社の同意ポリシーが優先されます。確認日のMicrosoft管理ポリシーでは、利用者は Mail.ReadBasic と Mail.Read に自分では同意できません。管理者の承認画面が出るのは、設定ミスとは限りません。

管理者の同意

あなたがクラウド アプリケーション管理者でない場合、同意ボタンは押しません。管理者へ、次の文面を渡します。クライアント シークレットは書きません。

件名: 練習用アプリの委任アクセス許可の同意をお願いします

アプリ名: Outlookメール表示（練習）
アプリケーション (クライアント) ID: （概要のクライアントIDだけ）
必要な許可: 委任の User.Read と Mail.ReadBasic
使わない許可: Mail.Send、Mail.ReadWrite、アプリケーションの許可
目的: サインインした本人の受信トレイの件名と受信日時を、本人の練習用Webアプリに表示します。送信、削除、変更はしません。

管理者の公式手順は、Entra ID、アプリの登録、対象アプリ、APIのアクセス許可を開き、内容を確認してから Grant admin consent を押す、です。日本語画面では「管理者の同意を与えます」の系統のボタンです。同意できる最小ロールは、この委任の許可ならクラウド アプリケーション管理者です。成功すると、状態列が組織に対して付与済みになります。

使う方式は、OAuth 2.0の認可コードフローに、PKCEを足したものです。認可コードは「通行証と交換できる、すぐ期限が切れる引換券」です。PKCEは、その引換券を盗まれても、発行時の答えを知るアプリ以外が交換できないようにする仕組みです。

認可の窓口は https://login.microsoftonline.com/{テナントID}/oauth2/v2.0/authorize です。通行証の窓口は同じホストの /oauth2/v2.0/token です。会社専用アプリでは、common ではなくテナントIDを使います。

Webサーバー型とSPA型

接続先の置き場所

既存のアプリが Swift や iOS だけの場合、そこに Outlook 接続を足しません。練習用の Web アプリは、別の新しいフォルダに作ります。

フォルダ名の例は outlook-mail-reader です。すでに動いている別のアプリのフォルダや、会社の共有フォルダの中には作りません。

Cursorへ貼る

1. Cursorで、新しいウィンドウを開きます。フォルダはまだ空で構いません。
2. Cursor実装プロンプトを開き、中の指示をコピーします。
3. 「ここから下を、新しいCursorチャットへ貼る」の枠内を、チャットへ貼ります。
4. Cursorが新しいフォルダにファイルを作るのを待ちます。既存の別アプリにファイルが増えていたら、その変更は採用しません。
5. できた .env.dev.example を複製し、名前を .env.dev にします。
6. プレースホルダを、第5章で保存した値に差し替えます。この差し替えはチャットでは行いません。

プロンプトがCursorに頼む機能は、次の7つです。

• Microsoftでサインインするボタン
• POSTの認証コールバック
• サーバーセッションでのトークン取得
• Graphの /me への接続
• 受信トレイの件名と受信日時の読み取り
• トークンを隠したエラー表示
• セッション破棄を含むログアウト

接続の要所

スコープはこの2つです。MSALが openid、profile、offline_access を足すのは、公式チュートリアルにも書かれている既定の動作です。

const scopes = ["User.Read", "Mail.ReadBasic"];

メール取得は GET だけです。受信日時は UTC で届くので、画面では東京の時刻に直します。

const url = process.env.GRAPH_API_ENDPOINT + "v1.0/me/mailFolders/inbox/messages";
const response = await axios.get(url, {
  headers: { Authorization: `Bearer ${accessToken}` },
  params: {
    "$select": "subject,receivedDateTime",
    "$top": 10,
    "$orderby": "receivedDateTime desc"
  }
});

テストは、アプリのフォルダだけで行います。ターミナルでそのフォルダを開き、次を実行します。

npm install
npm start

ブラウザで http://localhost:3000 を開きます。成功条件は上から順に見ます。1つ失敗したら、次へ進まず第10章へ移ります。

1. Microsoftログイン成功: 会社のアカウントで戻り、アプリのトップがエラーでは無い。
2. 必要な権限の同意: 同意画面に出るメール関連が、基本の読み取りである。送信や、すべてのメールボックスの読み取りが含まれていたら、その場でキャンセルし、第6章の許可を見直します。
3. /me 取得成功: 自分の表示名、または会社のメールアドレスがアプリに出る。
4. /me/mailFolders/inbox/messages 取得成功: 受信トレイの一覧がエラーでは無い。
5. 画面に件名と受信日時が出る。日時は日本時間で読める。
6. 不要な送信、変更、削除が0件である。画面に送信ボタンが無く、Outlookの送信済みにもテスト由来の新着が無い。

エラー番号を、この順で見ます。番号が分かるときは、その段だけを直します。

Microsoft 365アカウントの違い

会社のアカウントは、組織のディレクトリに属します。@outlook.com や @hotmail.com の個人アカウントは別です。第4章で「この組織のみ」を選んだアプリには、個人アカウントでは入れません。会社のメールを個人アカウントへ転送して読む方法も、この教科書では使いません。

• 最小権限: 一覧に残す委任は User.Read と Mail.ReadBasic です。本文が必要になるまで Mail.Read には上げません。
• 秘密情報: シークレットの値、通行証、認可コード、セッション秘密は .env.dev とサーバーセッションの中だけです。
• ログ: MSALの piiLoggingEnabled は false です。エラー画面には番号と状態だけを出します。
• 練習の終了: 使い終わったらログアウトし、ターミナルでサーバーを止めます。

アクセス権の取り消し

myapps で利用者が取り消せるのは、利用者自身が同意した許可です。組織全体の管理者同意は、クラウド アプリケーション管理者以上が、エンタープライズ アプリケーションの「管理者の同意」タブから取り消します。ユーザー同意タブは、確認日の公式説明ではポータルから取り消せません。

アプリ登録の削除は、概要の Delete です。公式は、完全に消す前に無効化も検討するよう案内しています。エンタープライズ アプリケーションの削除は30日間復元できます。アプリ登録の削除画面では、表示された結果を読んでから確定します。通行証は削除の瞬間に必ず無効になるとは限らないので、サーバーも止めてセッションを捨てます。

会社の管理者への確認事項

• 一般社員がアプリを登録してよいか。
• Mail.ReadBasic の委任に、管理者同意を出してよいか。
• 練習アプリを本人だけに制限するか。
• 使っているのが通常のグローバルクラウドか。
• 練習が終わったアプリを、いつ削除するか。

本番公開前チェックリスト

localhost の練習が成功しただけでは、インターネットへ公開しません。公開前に、次がすべて揃ってから管理者と再確認します。

• 戻り先が https である。
• クライアント シークレットではなく、公式が本番で推奨する証明書へ切り替えている。
• セッションのクッキーが secure である。
• シークレットと .env.dev がGitの履歴に一度も入っていない。
• ログ収集サービスへ通行証が送られない。
• 許可が User.Read と Mail.ReadBasic の委任のままである。
• 送信、削除、既読変更のコードが存在しない。

本文の点線を押すと、ここと同じ説明がダイアログで開きます。印刷したPDFでも読めるように、ここに全文を置いています。