Список сообщений

Пространство имен: microsoft.graph

Получение сообщений в почтовом ящике пользователя, выполнившего вход (в том числе сообщений в папках "Удаленные" и "Несрочные").

В зависимости от размера страницы и данных почтового ящика получение сообщений из почтового ящика может повлечь множество запросов. По умолчанию страница содержит 10 сообщений. Используйте параметр $top, чтобы настроить размер страницы в диапазоне от 1 до 1000.

Чтобы сократить время отклика, используйте параметр $select для указания точных свойств, которые вам нужны. См. пример 1 ниже. Настройте значения для $select и $top, особенно при необходимости использовании большего размера страницы, так как возврат страницы с сотнями сообщений, каждое из которых содержит полные полезные данные отклика, может привести к истечению времени ожидания шлюза (HTTP 504).

Для получения следующей странице с сообщениями, просто примените весь URL-адрес, возвращаемый в @odata.nextLink, для другого запроса на получение сообщений. Этот URL-адрес включает любые параметры запроса, которые указаны в первоначальном запросе.

Не пытайтесь извлечь $skip значение из @odata.nextLink URL-адреса для управления ответами. Данный API использует значение $skip для учета всех элементов, просмотренных в почтовом ящике пользователя, и возврата элементов типа сообщение на странице. Таким образом, существует возможность, что даже в первоначальном ответе, значение $skip будет больше, чем размер страницы. Дополнительные сведения см. в статье Разбивка данных Microsoft Graph по страницам в приложении

В настоящее время эта операция возвращает текст сообщения только в формате HTML.

Существует два сценария, когда приложение может получить сообщения из папки почты другого пользователя:

• У приложения есть разрешения для приложений; или
• У приложения есть соответствующие делегированные разрешения от одного пользователя, а другой пользователь поделился с ним папкой почты или предоставил ему делегированный доступ. См. подробные сведения и пример.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	Mail.ReadBasic	Mail.ReadWrite, Mail.Read
Делегированные (личная учетная запись Майкрософт)	Mail.ReadBasic	Mail.ReadWrite, Mail.Read
Приложение	Mail.ReadBasic.All	Mail.ReadWrite, Mail.Read

HTTP-запрос

Для получения всех сообщений в почтовом ящике пользователя:

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

Для получения сообщений из определенной папки в почтовом ящике пользователя:

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

Необязательные параметры запросов

Этот метод поддерживает параметры запросов OData для настройки ответа.

Использование операторов filter и orderby в одном запросе

При использовании операторов $filter и $orderby в одном запросе на получение сообщений необходимо указать свойства, соблюдая указанные ниже условия.

1. Свойства, используемые в операторе $orderby, также должны использоваться в операторе $filter.
2. Свойства, используемые в операторе $orderby, представлены в том же порядке, что и для оператора $filter.
3. Свойства, присутствующие в операторе $orderby, представлены в операторе $filter раньше всех остальных свойств.

В противном случае возникнет следующая ошибка:

• Код ошибки: InefficientFilter
• Сообщение об ошибке: The restriction or sort order is too complex for this operation.

Заголовки запросов

Имя	Тип	Описание
Authorization	string	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Prefer: outlook.body-content-type	string	Формат возвращаемых свойств body и uniqueBody. Возможные значения: "text" или "html". Если заголовок не указан, свойства body и uniqueBody возвращаются в формате HTML. Необязательный параметр.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и коллекцию объектов Message в тексте отклика.

Примеры

Пример 1. Перечисление всех сообщений

Запрос

Вот пример, который получает первые 10 сообщений по умолчанию в почтовом ящике вошедшего в систему пользователя. $select используется для получения подмножества свойств каждого сообщения в ответе.

HTTP

GET https://graph.microsoft.com/v1.0/me/messages?$select=sender,subject

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "sender","subject" };
});

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Select: [] string {"sender","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"sender", "subject"};
});

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.select('sender,subject')
	.get();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["sender","subject"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "sender,subject" 

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		select = ["sender","subject"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

Ниже показан пример отклика. Чтобы получить следующую страницу с сообщениями, примените URL-адрес, возвращенный в @odata.nextLink, для последующего запроса GET.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages(sender,subject)",
    "value": [
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
            "id": "AAMkAGUAAAwTW09AAA=",
            "subject": "You have late tasks!",
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Planner",
                    "address": "noreply@Planner.Office365.com"
                }
            }
        }
    ]
}