mailFolders を一覧表示する
名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
サインイン中のユーザーのルート フォルダーからメール フォルダー コレクションを直接取得します。 返されたコレクションには、ルート直下にあるメール検索フォルダーが含まれています。
既定では、この操作は隠しフォルダーを返しません。 クエリ パラメーター includeHiddenFolders を使用して、それらを応答に含めます。 この操作では、メールボックス内のすべてのメール フォルダーが返されるのではなく、ルート フォルダーの子フォルダーのみが返されます。 メールボックス内のすべてのメール フォルダーを返すには、各子フォルダーを 個別に走査する必要があります。
この API は、次の国内クラウド展開で使用できます。
| グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。
| アクセス許可の種類 | 最小特権アクセス許可 | 特権の高いアクセス許可 |
|---|---|---|
| 委任 (職場または学校のアカウント) | Mail.ReadBasic | Mail.ReadWrite、Mail.Read |
| 委任 (個人用 Microsoft アカウント) | Mail.ReadBasic | Mail.ReadWrite、Mail.Read |
| アプリケーション | Mail.ReadBasic.All | Mail.ReadWrite、Mail.Read |
HTTP 要求
指定したユーザーのメールボックス内のルート フォルダー内のすべてのメール フォルダーを取得するには (非表示のメール フォルダーを除く)。
GET /me/mailFolders
GET /users/{id | userPrincipalName}/mailFolders
非表示のメール フォルダーを応答に含めるには、以下のようにします。
GET /me/mailFolders/?includeHiddenFolders=true
GET /users/{id | userPrincipalName}/mailFolders/?includeHiddenFolders=true
オプションのクエリ パラメーター
非表示 (isHidden プロパティが true) のものを含むすべてのメール フォルダーのリストを返すには、HTTP 要求セクションで示したように、リクエスト URL で true としての includeHiddenFolders クエリ パラメーターと指定します。
このメソッドは、応答のカスタマイズに役立つ OData クエリ パラメーター をサポートします。
要求ヘッダー
| ヘッダー | 値 |
|---|---|
| Authorization | ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。 |
要求本文
このメソッドには、要求本文を指定しません。
応答
成功した場合、このメソッドは 200 OK 応答コードと、応答本文で mailFolder オブジェクトのコレクションを返します。
例
例 1: サインインしているユーザーのメールボックス内のメール フォルダーを一覧表示する
この例では、mailSearchFolder オブジェクトを応答に含めます。 メール検索フォルダーは、[受信トレイ] の下にある子フォルダーで、表示名は "Weekly digests" です。
要求
次の例は要求を示しています。
GET https://graph.microsoft.com/beta/me/mailFolders
応答
受信トレイの下の子フォルダーである mailSearchFolder を含む応答の例を次に示します。
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders",
"value": [
{
"id": "AQMkADYAAAIBXQAAAA==",
"displayName": "Archive",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "archive",
"isHidden": false
},
{
"id": "AQMkADYAAAIBFQAAAA==",
"displayName": "Conversation History",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 1,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "conversationhistory",
"isHidden": false
},
{
"id": "AQMkADYAAAIBCgAAAA==",
"displayName": "Deleted Items",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "deleteditems",
"isHidden": false
},
{
"id": "AQMkADYAAAIBDwAAAA==",
"displayName": "Drafts",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "drafts",
"isHidden": false
},
{
"id": "AQMkADYAAAIBDAAAAA==",
"displayName": "Inbox",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 1,
"unreadItemCount": 70,
"totalItemCount": 71,
"wellKnownName": "inbox",
"isHidden": false
},
{
"@odata.type": "#microsoft.graph.mailSearchFolder",
"id": "AAMkADYRAAAZg1yTAAA=",
"displayName": "Weekly digests",
"parentFolderId": "AQMkADYAAAIBDAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 4,
"totalItemCount": 5,
"wellKnownName": null,
"isHidden": false,
"isSupported": true,
"filterQuery": "contains(subject, 'weekly digest')"
},
{
"id": "AQMkADYAAAIBGQAAAA==",
"displayName": "Junk Email",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "junkemail",
"isHidden": false
},
{
"id": "AQMkADYAAAIBCwAAAA==",
"displayName": "Outbox",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "outbox",
"isHidden": false
},
{
"id": "AQMkADYAAAIBCQAAAA==",
"displayName": "Sent Items",
"parentFolderId": "AQMkADYAAAIBCAAAAA==",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "sentitems",
"isHidden": false
}
]
}
ヒント
コレクションが既定のページ サイズ (10 項目) を超えた場合、 応答で @odata.nextLink プロパティが返され、使用可能な項目が増え、次のページの項目の要求 URL が指定されます。
ページ サイズはオプションのクエリ文字列パラメーターで制御できます。
例 2: サインインしたユーザーのメールボックスに隠しフォルダーを含める
この例では、クエリ パラメーターを includeHiddenFolders 使用して、非表示のメール フォルダーを含むメール フォルダーの一覧を取得します。 応答には、 isHidden が に true設定されている "クラッター" フォルダーが含まれます。
要求
GET https://graph.microsoft.com/beta/me/mailFolders/?includeHiddenFolders=true
応答
次の例は応答を示しています。
注: ここに示す応答オブジェクトは、読みやすさのために短縮され、ユーザーのメールボックス内のすべての既定のフォルダーは含まれません。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders",
"value": [
{
"id": "AAMkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWAAA=",
"displayName": "Clutter",
"parentFolderId": "AAMkADg3NTY5MDg4LWMzYmQtEIAAA=",
"childFolderCount": 0,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": null,
"isHidden": true
},
{
"id": "AAMkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWAAA=",
"displayName": "Conversation History",
"parentFolderId": "AAMkADg3NTY5MDg4LWMzYmQtEIAAA=",
"childFolderCount": 1,
"unreadItemCount": 0,
"totalItemCount": 0,
"wellKnownName": "conversationhistory",
"isHidden": false
}
]
}