メッセージを一覧表示するList messages

重要

Microsoft Graph の/betaバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。Use of these APIs in production applications is not supported.

サインイン中のユーザーのメールボックス内のメッセージを取得します (削除済みアイテムと低優先メール フォルダーを含む)。Get the messages in the signed-in user's mailbox (including the Deleted Items and Clutter folders).

ページ サイズとメールボックスのデータに応じ、メールボックスから取得するメッセージは複数の要求を発生します。Depending on the page size and mailbox data, getting messages from a mailbox can incur multiple requests. ページ サイズの規定値は、10 件のメッセージです。The default page size is 10 messages. メッセージの次のページを取得するには、@odata.nextLinkで返される URL 全体を単に次のメッセージ要求に適用するだけです。To get the next page of messages, simply apply the entire URL returned in @odata.nextLink to the next get-messages request. この URL は、最初の要求で指定された全てのクエリ パラメーターを含みます。This URL includes any query parameters you may have specified in the initial request.

応答を操作するために@odata.nextLink URL から$skip 値を抽出しようとしないでください。Do not try to extract the $skip value from the @odata.nextLink URL to manipulate responses. この API は$skip 値を使用し、メッセージの種類の項目のページを返すためにユーザーのメールボックス内で確認された全ての項目をカウントし続けます。This API uses the $skip value to keep count of all the items it has gone through in the user's mailbox to return a page of message-type items. そのため、最初の要求の場合も$skip 値がページ サイズより大きくなる可能性があります。It's therefore possible that even in the initial response, the $skip value is larger than the page size. 詳細については、アプリで Microsoft Graph データをページングするを参照してください。For more information, see Paging Microsoft Graph data in your app.

メッセージにフィルターを適用し、サインインしているユーザーのメンションを含むメッセージのみを取得できます。You can filter on the messages and get only those that include a mention of the signed-in user.

既定では、操作にGET /me/messagesよってメンションプロパティは返されないことに注意してください。Note that by default, the GET /me/messages operation does not return the mentions property. $expand メッセージ内の各メンションの詳細を検索するには、クエリパラメーターを使用します。Use the $expand query parameter to find details of each mention in a message.

別のユーザーのメール フォルダーからアプリがメッセージを取得するシナリオは 2 つあります。There are two scenarios where an app can get messages in another user's mail folder:

  • アプリにアプリケーションのアクセス許可がある場合。またはIf the app has application permissions, or,
  • あるユーザーからアプリに適切な代理アクセス許可が与えられ、別のユーザーがそのユーザーとメール フォルダーを共有しているか、そのユーザーに代理アクセスを付与している場合。If the app has the appropriate delegated permissions from one user, and another user has shared a mail folder with that user, or, has given delegated access to that user. 詳細と例を参照してください。See details and an example.

権限Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) メール ReadBasic、Mail. 読み取り、ReadWriteMail.ReadBasic, Mail.Read, Mail.ReadWrite
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) メール ReadBasic、Mail. 読み取り、ReadWriteMail.ReadBasic, Mail.Read, Mail.ReadWrite
アプリケーションApplication -ReadBasic、mail. 読み取り、および書き込みMail.ReadBasic.All, Mail.Read, Mail.ReadWrite

HTTP 要求HTTP request

ユーザーのメールボックス内のすべてのメッセージを取得するTo get all the messages in a user's mailbox:

GET /me/messages
GET /users/{id | userPrincipalName}/messages

ユーザーのメールボックス内の特定のフォルダーにあるメッセージを取得するTo get messages in a specific folder in the user's mailbox:

GET /me/mailFolders/{id}/messages
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages

ユーザーのメールボックス内のすべてのメッセージを取得するには、次のようにします。To get all the messages in the user's mailbox that include a mention of the user:

GET /me/messages?$filter=mentionsPreview/isMentioned eq true
GET /users/{id | userPrincipalName}/messages?$filter=mentionsPreview/isMentioned eq true

オプションのクエリ パラメーターOptional query parameters

このメソッドは、応答をカスタマイズするための OData クエリ パラメーターをサポートします。This method supports the OData Query Parameters to help customize the response.

$filter MentionsPreviewプロパティの query パラメーターを使用すると、サインインしているユーザーを言及するメッセージを取得できます。You can use the $filter query parameter on the mentionsPreview property to get those messages that mention the signed-in user.

同じクエリで filter と orderby を使用するUsing filter and orderby in the same query

$orderby同じ$filterクエリを使用してメッセージを取得する場合は、次の方法でプロパティを指定してください。When using $filter and $orderby in the same query to get messages, make sure to specify properties in the following ways:

  1. $orderby表示されるプロパティは、に$filterも表示される必要があります。Properties that appear in $orderby must also appear in $filter.
  2. $orderby表示されるプロパティは、と同じ順序に$filterなります。Properties that appear in $orderby are in the same order as in $filter.
  3. に存在しないプロパティ$orderbyは、 $filterそのプロパティの前に表示されます。Properties that are present in $orderby appear in $filter before any properties that aren't.

失敗すると、次のエラーが発生します。Failing to do this results in the following error:

  • エラーコード:InefficientFilterError code: InefficientFilter
  • エラーメッセージ:The restriction or sort order is too complex for this operation.Error message: The restriction or sort order is too complex for this operation.

要求ヘッダーRequest headers

名前Name Type 説明Description
AuthorizationAuthorization stringstring ベアラー {トークン}。必須。Bearer {token}. Required.
Prefer: outlook.body-content-typePrefer: outlook.body-content-type stringstring body プロパティと uniqueBody プロパティが返されるときの形式です。The format of the body and uniqueBody properties to be returned in. 値は、"text" または "html" になります。Values can be "text" or "html". ヘッダーが指定されていない場合は、body プロパティと uniqueBody プロパティは HTML 形式で返されます。If the header is not specified, the body and uniqueBody properties are returned in HTML format. 省略可能。Optional.

要求本文Request body

このメソッドには、要求本文を指定しません。Do not supply a request body for this method.

応答Response

成功した場合、このメソッド200 OKは応答コードと、応答本文でmessageオブジェクトのコレクションを返します。If successful, this method returns a 200 OK response code and collection of message objects in the response body.

Example

要求 1Request 1

最初の例では、サインインしているユーザーのメールボックス内の既定の上位10個のメッセージを取得します。The first example gets the default, top 10 messages in the signed-in user's mailbox. $select を使用し、応答にメッセージごとのプロパティのサブセットを返します。It uses $select to return a subset of the properties of each message in the response.

GET https://graph.microsoft.com/beta/me/messages?$select=sender,subject
応答 1Response 1

以下は、応答の例です。Here is an example of the response. メッセージの次のページを取得するには、@odata.nextLinkで返されるURL を後続の Get 要求に適用します。To get the next page of messages, apply the URL returned in @odata.nextLink to a subsequent GET request.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages(sender,subject)",
    "@odata.nextLink": "https://graph.microsoft.com/beta/me/messages?$select=sender%2csubject&$skip=14",
    "value": [
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
            "id": "AAMkAGUAAAwTW09AAA=",
            "subject": "You have late tasks!",
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Planner",
                    "address": "noreply@Planner.Office365.com"
                }
            }
        },
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4D1e\"",
            "id": "AAMkAGUAAAq5QKlAAA=",
            "subject": "You have late tasks!",
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Planner",
                    "address": "noreply@Planner.Office365.com"
                }
            }
        },
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4D0v\"",
            "id": "AAMkAGUAAAq5QKkAAA=",
            "subject": "Your Azure AD Identity Protection Weekly Digest",
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Azure",
                    "address": "azure-noreply@microsoft.com"
                }
            }
        },
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4DsN\"",
            "id": "AAMkAGUAAAq5QKjAAA=",
            "subject": "Use attached file",
            "sender": {
                "emailAddress": {
                    "name": "Megan Bowen",
                    "address": "MeganB@contoso.OnMicrosoft.com"
                }
            }
        },
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4Dq9\"",
            "id": "AAMkAGUAAAq5QKiAAA=",
            "subject": "Original invitation",
            "sender": {
                "emailAddress": {
                    "name": "Megan Bowen",
                    "address": "MeganB@contoso.OnMicrosoft.com"
                }
            }
        },
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4Dq1\"",
            "id": "AAMkAGUAAAq5QKhAAA=",
            "subject": "Koala image",
            "sender": {
                "emailAddress": {
                    "name": "Megan Bowen",
                    "address": "MeganB@contoso.OnMicrosoft.com"
                }
            }
        },
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4Dqp\"",
            "id": "AAMkAGUAAAq5QKgAAA=",
            "subject": "Sales invoice template",
            "sender": {
                "emailAddress": {
                    "name": "Megan Bowen",
                    "address": "MeganB@contoso.OnMicrosoft.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.eventMessageRequest",
            "@odata.etag": "W/\"CwAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAq4Dfa\"",
            "id": "AAMkAGUAAAq5T8tAAA=",
            "subject": "Review strategy for Q3",
            "sender": {
                "emailAddress": {
                    "name": "Megan Bowen",
                    "address": "MeganB@contoso.OnMicrosoft.com"
                }
            }
        }
    ]
}
要求 2Request 2

次の例では、サインインしているユーザーのメールボックス内のすべてのメッセージに対して、ユーザーに言及するメッセージをフィルター処理します。The next example filters all messages in the signed-in user's mailbox for those that mention the user. また、を$select使用して、応答内の各メッセージのプロパティのサブセットを返します。It also uses $select to return a subset of the properties of each message in the response.

この例では、クエリパラメーター文字列にスペース文字の URL エンコーディングも組み込まれています。The example also incorporates URL encoding for the space characters in the query parameter string.

GET https://graph.microsoft.com/beta/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview
応答 2Response 2

以下は、応答の例です。注:簡潔にするために、ここに示す応答オブジェクトは切り詰められている場合があります。すべてのプロパティは実際の呼び出しから返されます。Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 987

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#me/messages(subject,sender,receivedDateTime,mentionsPreview)",
  "value":[
    {
      "@odata.id":"https://graph.microsoft.com/beta/users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/messages('AQMkADJmMTUAAAgVZAAAA')",
      "@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAATI\"",
      "id":"AQMkADJmMTUAAAgVZAAAA",
      "receivedDateTime":"2016-07-21T07:40:21Z",
      "subject":"Re: Start planning soon",
      "sender":{
        "emailAddress":{
          "name":"Randi Welch",
          "address":"randiw@contoso.onmicrosoft.com"
        }
      },
      "mentionsPreview":{
        "isMentioned":true
      }
    },
    {
      "@odata.id":"https://graph.microsoft.com/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Messages('AQMkADJmMTUAAAjwVAAAA')",
      "@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAEGj\"",
      "id":"AQMkADJmMTUAAAjwVAAAA",
      "receivedDateTime":"2016-07-21T07:40:20Z",
      "subject":"Re: Start planning soon",
      "sender":{
        "emailAddress":{
          "name":"Randi Welch",
          "address":"randiw@contoso.onmicrosoft.com"
        }
      },
      "mentionsPreview":{
        "isMentioned":true
      }
    }
  ]
}
要求 3Request 3

3番目の例では、 Prefer: outlook.body-content-type="text"ヘッダーを使用して、各メッセージの本文およびuniqueBodyプロパティをテキスト形式で取得する方法を示します。The third example shows how to use a Prefer: outlook.body-content-type="text" header to get the body and uniqueBody properties of each message in text format.

GET https://graph.microsoft.com/beta/me/messages?$select=subject,body,bodyPreview,uniqueBody
Prefer: outlook.body-content-type="text"
応答 3Response 3

以下は、応答の例です。Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 2704

{
    "@odata.context":"https://graph.microsoft.com/beta/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/messages(subject,body,bodyPreview,uniqueBody)",
    "value":[
        {
            "@odata.type":"#microsoft.graph.eventMessageRequest",
            "@odata.etag":"W/\"CwAAABYAAABmWdbhEgBXTophjCWt81m9AAAoZYj5\"",
            "id":"AAMkAGIAAAoZCfIAAA=",
            "subject":"Orientation ",
            "bodyPreview":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.",
            "body":{
                "contentType":"text",
                "content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
            },
            "uniqueBody":{
                "contentType":"text",
                "content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
            }
        },
        {
            "@odata.etag":"W/\"CQAAABYAAABmWdbhEgBXTophjCWt81m9AAAoZYj4\"",
            "id":"AAMkAGIAAAoZCfHAAA=",
            "subject":"Welcome to our group!",
            "bodyPreview":"Welcome to our group, Dana! Hope you will enjoy working with us !\r\n\r\nWould you like to choose a day for our orientation from the available times below:\r\n\r\n\r\nDate\r\n        Time\r\n\r\nApril 14, 2017\r\n        1-3pm\r\n\r\nApril 21, 2017\r\n        10-12noon\r\n\r\n\r\n\r\nTh",
            "body":{
                "contentType":"text",
                "content":"Welcome to our group, Dana! Hope you will enjoy working with us [\ud83d\ude0a] [\ud83d\ude0a] [\ud83d\ude0a] [\ud83d\ude0a] [\ud83d\ude0a] !\r\n\r\nWould you like to choose a day for our orientation from the available times below:\r\n\r\n\r\nDate\r\n        Time\r\n\r\nApril 14, 2017\r\n        1-3pm\r\n\r\nApril 21, 2017\r\n        10-12noon\r\n\r\n\r\n\r\nThanks!\r\n\r\n"
            },
            "uniqueBody":{
                "contentType":"text",
                "content":"Welcome to our group, Dana! Hope you will enjoy working with us [\ud83d\ude0a] [\ud83d\ude0a] [\ud83d\ude0a] [\ud83d\ude0a] [\ud83d\ude0a] !\r\nWould you like to choose a day for our orientation from the available times below:\r\n\r\nDate\r\n        Time\r\n\r\nApril 14, 2017\r\n        1-3pm\r\n\r\nApril 21, 2017\r\n        10-12noon\r\n\r\n\r\nThanks!\r\n"
            }
        },
        {
            "@odata.etag":"W/\"CQAAABYAAABmWdbhEgBXTophjCWt81m9AAAAAAjr\"",
            "id":"AQMkAGIAAAIJTQAAAA==",
            "subject":"Welcome aboard!",
            "bodyPreview":"Welcome to the Support group!",
            "body":{
                "contentType":"text",
                "content":"Welcome to the Support group!\r\n"
            },
            "uniqueBody":{
                "contentType":"text",
                "content":"Welcome to the Support group!\r\n"
            }
        }
    ]
}