outlook-use

# outlook-use Python から Microsoft Graph API 経由で Outlook のメールとカレンダーを操作する。 認証は MSAL デバイスコードフロー（初回のみブラウザ認証、以降はトークンキャッシュを利用）。 Windows / macOS / Linux のいずれの Python からでも動作する。 セットアップ手順: [`references/setup-guide.md`](references/setup-guide.md) --- ## 前提条件 ```bash pip install msal requests ``` **アプリ登録不要。** 以下のいずれかの認証方法を自動選択する（優先順）: | 優先度 | 方法 | 必要なもの | |-------|------|-----------| | 1 | **Azure CLI セッション** | `az login` でサインイン済みであること | | 2 | **MSAL デバイスコードフロー** | `pip install msal`（初回のみブラウザ認証） | 詳細は [references/setup-guide.md](references/setup-guide.md) を参照。 --- ## 権限スコープ一覧 | 操作 | 必要スコープ | |------|------------| | メール読み取り | `Mail.Read` | | メール送信 | `Mail.Send` | | カレンダー読み取り | `Calendars.Read` | | カレンダー作成・更新・削除 | `Calendars.ReadWrite` | | オフライン（トークン更新） | `offline_access` | > **スコープ最小化の原則**: 各スクリプトは必要最小限のスコープのみ要求する。読み取りスクリプトは書き込みスコープを要求しない。 --- ## 操作一覧 | 操作 | スクリプト | 主なスコープ | |------|-----------|------------| | メール一覧・検索 | `get_mail.py` | `Mail.Read` | | メール送信 | `send_mail.py` | `Mail.Send` | | カレンダー予定管理 | `calendar_events.py` | `Calendars.ReadWrite` | --- ## メール読み取り（get_mail.py） 受信トレイやフォルダのメールを一覧・検索する。 ```bash # 受信トレイの直近 20 件を表示 python scripts/get_mail.py # 未読メールのみ表示 python scripts/get_mail.py --unread-only # 件数を指定して取得 python scripts/get_mail.py --top 50 # 送信済みフォルダを確認 python scripts/get_mail.py --folder sentitems # キーワードで検索 python scripts/get_mail.py --search "会議" # 本文も含めて表示 python scripts/get_mail.py --show-body # JSON 形式で出力 python scripts/get_mail.py --json # メール ID を指定して本文を表示 python scripts/get_mail.py --message-id <message-id> ``` ### 対応フォルダ名 | フォルダ | 名前 | |---------|------| | 受信トレイ | `inbox` | | 送信済み | `sentitems` | | 下書き | `drafts` | | 削除済み | `deleteditems` | | 迷惑メール | `junkemail` | --- ## メール送信（send_mail.py） 新規メールを送信する。 ```bash # 基本的な送信 python scripts/send_mail.py \ --to "example@example.com" \ --subject "件名" \ --body "本文" # 複数宛先（カンマ区切り） python scripts/send_mail.py \ --to "a@example.com,b@example.com" \ --subject "件名" \ --body "本文" # CC / BCC を指定 python scripts/send_mail.py \ --to "a@example.com" \ --cc "b@example.com" \ --bcc "c@example.com" \ --subject "件名" \ --body "本文" # HTML 形式で送信 python scripts/send_mail.py \ --to "a@example.com" \ --subject "件名" \ --body "<b>太字</b>テキスト" \ --html # 送信済みフォルダに保存しない python scripts/send_mail.py \ --to "a@example.com" \ --subject "件名" \ --body "本文" \ --no-save ``` --- ## カレンダー管理（calendar_events.py） 予定の一覧取得・作成・削除を行う。 ### 予定一覧 ```bash # 今後の予定を 20 件表示 python scripts/calendar_events.py list # 件数を指定 python scripts/calendar_events.py list --top 50 # 日付範囲でフィルタ python scripts/calendar_events.py list --start 2025-01-01 --end 2025-01-31 # JSON 形式で出力 python scripts/calendar_events.py list --json ``` ### 予定作成 ```bash # 基本的な予定作成（タイムゾーンは Asia/Tokyo がデフォルト） python scripts/calendar_events.py create \ --subject "チームミーティング" \ --start "2025-01-15T10:00:00" \ --end "2025-01-15T11:00:00" # 場所・参加者・本文を指定 python scripts/calendar_events.py create \ --subject "プロジェクトレビュー" \ --start "2025-01-15T14:00:00" \ --end "2025-01-15T15:00:00" \ --location "会議室A" \ --body "月次レビューです" \ --attendees "a@example.com,b@example.com" # 終日予定 python scripts/calendar_events.py create \ --subject "全社休日" \ --start "2025-01-15" \ --end "2025-01-15" \ --all-day # タイムゾーンを指定 python scripts/calendar_events.py create \ --subject "海外MTG" \ --start "2025-01-15T09:00:00" \ --end "2025-01-15T10:00:00" \ --timezone "UTC" ``` ### 予定削除 ```bash # 予定 ID を指定して削除（ID は list コマンドで確認） python scripts/calendar_events.py delete --event-id <event-id> ``` --- ## 基本ワークフロー ### Step 1: 初回セットアップ 1. `pip install msal requests` でパッケージをインストール 2. Azure CLI がある場合は `az login` でサインイン（以降はStep 2不要） ### Step 2: 認証 スクリプト実行時に認証方法が自動選択される: **Azure CLI が利用可能な場合（`az login` 済み）:** ``` Azure CLI セッションで認証しました。 ``` 追加操作は不要。 **Azure CLI が利用できない場合（MSAL フォールバック）:** ``` Azure CLI が利用できません。MSAL デバイスコードフローを使用します。 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXXX to authenticate. ``` ブラウザでコードを入力して認証する。トークンは `~/.outlook_graph_cache.json` にキャッシュされ、以降は再認証不要（有効期限内）。 --- ## エラー対処 | エラー | 対処 | |--------|------| | `Insufficient privileges` | Azure AD 管理者に必要スコープの権限付与を依頼 | | `msal not found` | `pip install msal requests` を実行 | | Azure CLI 認証エラー | `az login` を再実行するか、MSAL フォールバックを使用 | | MSAL 認証ループ | `~/.outlook_graph_cache.json` を削除して再認証 | --- ## スクリプト構成 ``` scripts/ ├── auth.py ← MSAL 認証共通ヘルパー（直接実行しない） ├── get_mail.py ← メール読み取り ├── send_mail.py ← メール送信 └── calendar_events.py ← カレンダー管理（list / create / delete） references/ └── setup-guide.md ← Azure AD 設定・初回セットアップ手順 ```