LINE WORKS API メールフォルダ内のメールリストの取得

# LINE WORKS メール フォルダ内のメール リスト取得

LINE WORKS の API を使用して、特定のメール フォルダ内に含まれるメールのリストを取得する方法を解説します。本記事では、Google Colab を活用して、簡単に実行できる Python スクリプトを紹介します。

## 概要

LINE WORKS のメール API を使用することで、次のような操作が可能です：

- 指定したメール フォルダ内のメール リストを取得
- 未読メールや添付ファイル付きメールなどの条件でフィルタリング
- リスト結果をページ分割で取得

## 必要な準備

### 1. アクセストークンの取得

メール API を使用するには、**User Account 認証**によるアクセストークンが必要です。アクセストークンの取得方法については、以下の記事をご参照ください：

- [LINE WORKS User Account 認証でアクセストークンを生成 (Qiita)](https://qiita.com/iwaohig/items/a7392f2d09b6fc70d8bb)

**注意**：アクセストークンには `mail` または `mail.read` スコープが含まれている必要があります。

### 2. Google Colab の準備

以下のリンクから Google Colab ノートブックにアクセスして、サンプル コードをそのまま試すことができます：

[Google Colab: メール フォルダ内のメール リスト取得](https://colab.research.google.com/drive/1G26C4L_lK5J9AZRzFMrDUDjE0HRuHDzW?usp=sharing)

## サンプル コード

以下は、Google Colab 上で動作する Python スクリプトのサンプルです。

```python
# 必要なライブラリをインストール
!pip install requests

# ライブラリのインポート
import requests
import json

# 設定変数
ACCESS_TOKEN = "your_access_token"  # @param {type:"string"}
USER_ID = "me"  # @param {type:"string"} "me" または LINE WORKS のユーザー ID
FOLDER_ID = "0"  # @param {type:"string"} メール フォルダ ID

# 取得オプション
COUNT = 10  # @param {type:"integer"} 取得するメールの数
IS_UNREAD = False  # @param {type:"boolean"} 未読メールのみ取得する場合は True
SEARCH_FILTER_TYPE = "all"  # @param ["all", "mark", "attach", "tome"]

# API サーバー
API_SERVER = "https://www.worksapis.com"
API_ENDPOINT = f"{API_SERVER}/v1.0/users/{USER_ID}/mail/mailfolders/{FOLDER_ID}/children"

# メール リスト取得 API の呼び出し
def get_mail_list(access_token, count, is_unread, search_filter_type):
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    }
    params = {
        "count": count,
        "isUnread": str(is_unread).lower(),
        "searchFilterType": search_filter_type,
    }
    response = requests.get(API_ENDPOINT, headers=headers, params=params)

    # レスポンスに基づく出力
    if response.status_code == 200:
        print("✅ メール リストを取得しました！")
        result = response.json()
        print(f"フォルダ名: {result['folderName']}")
        print(f"未読メール数: {result['unreadCount']}")
        print(f"メール総数: {result['totalCount']}")
        print("メール リスト:")
        print(json.dumps(result["mails"], indent=4, ensure_ascii=False))
    else:
        print(f"❌ メール リストの取得に失敗しました。ステータスコード: {response.status_code}")
        print(response.text)

# メール リスト取得 API を実行
get_mail_list(ACCESS_TOKEN, COUNT, IS_UNREAD, SEARCH_FILTER_TYPE)
```

## 入力例

- **`ACCESS_TOKEN`**: **User Account 認証**によるアクセストークン
- **`USER_ID`**: `"me"` または LINE WORKS のユーザー ID
- **`FOLDER_ID`**: メール フォルダの ID
- **`COUNT`**: 取得するメール数（最大 200 件）
- **`IS_UNREAD`**: 未読メールのみ取得する場合は `True`
- **`SEARCH_FILTER_TYPE`**:
  - `all`: すべてのメール（デフォルト）
  - `mark`: 重要メール
  - `attach`: 添付ファイル付きメール
  - `tome`: 自分宛のメール

## 実行結果

### 成功時

```plaintext
✅ メール リストを取得しました！
フォルダ名: 受信トレイ
未読メール数: 20
メール総数: 100
メール リスト:
[
    {
        "mailId": 12345,
        "status": "Unread",
        "subject": "テストメール",
        "from": {"email": "example@example.com"},
        "receivedTime": "2024-12-15T00:00:00+09:00"
    },
    ...
]
```

### 失敗時（例: スコープ不足）

```plaintext
❌ メール リストの取得に失敗しました。ステータスコード: 403
{"code": "ACCESS_DENIED", "description": "Access is denied for userId."}
```

## 注意事項

1. **アクセストークンのスコープ**
   - アクセストークンには `mail` または `mail.read` スコープが含まれている必要があります。

2. **メール フォルダ ID の取得**
   - フォルダ ID は、[メール フォルダ リスト取得 API](https://developers.worksmobile.com/jp/docs/mail-mailfolders) で取得できます。

3. **取得制限**
   - 取得件数は最大 200 件です。

---

LINE WORKS メール API を活用して、メールの自動化や管理を効率化しましょう！