Listar mensagens

Artigo
07/18/2022
14 minutos para o fim da leitura

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor de versão.

Obtenha as mensagens na caixa de correio do usuário conectado (incluindo as pastas Itens Excluídos e Email Secundário).

Dependendo do tamanho da página e dos dados da caixa de correio, a obtenção de mensagens de uma caixa de correio pode incorrer em várias solicitações. O tamanho de página padrão é 10 mensagens. Use $top para personalizar o tamanho da página, no intervalo de 1 a 1000.

Para melhorar o tempo de resposta da operação, use $select para especificar as propriedades exatas de que você precisa; consulte exemplo 1 abaixo. Ajuste os valores para $select e $top, especialmente quando você deve usar um tamanho de página maior, pois retornar uma página com centenas de mensagens, cada uma com uma carga útil de resposta completa, pode acionar o tempo limite do gateway (HTTP 504).

Para obter a próxima página de mensagens, basta aplicar a URL inteira retornada em @odata.nextLink à próxima solicitação de obtenção de mensagens. Esta URL inclui todos os parâmetros de consulta que você especificou na solicitação inicial.

Não tente extrair o valor $skip da URL @odata.nextLink para manipular respostas. Essa API usa o valor $skip para manter a contagem de todos os itens pelos quais passou na caixa de correio do usuário para retornar uma página de itens do tipo mensagem. Portanto, é possível que, mesmo na resposta inicial, o valor $skip seja maior que o tamanho da página. Para mais informações, consulte Paginação de dados do Microsoft Graph em seu aplicativo.

Você pode filtrar as mensagens e obter apenas aquelas que incluem uma menção do usuário conectado. Veja um exemplo abaixo. Por padrão, a GET /me/messages operação não retorna a propriedade de menções . Use o $expand parâmetro de consulta para localizar detalhes de cada menção em uma mensagem.

Existem dois cenários em que um aplicativo pode receber mensagens na pasta de email de outro usuário:

Se o aplicativo tiver permissões de aplicativo ou
Se o aplicativo tiver as permissões delegadas apropriadas de um usuário e outro usuário tiver compartilhado uma pasta de email com esse usuário, ou tiver concedido acesso delegado a esse usuário. Veja detalhes e um exemplo.

Observação Lembre-se da questão conhecida essa operação inclui mensagens de chat do Microsoft Teams em sua resposta.

Permissões

Uma das seguintes permissões é obrigatória para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão	Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante)	Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Delegado (conta pessoal da Microsoft)	Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Aplicativo	Mail.ReadBasic.All, Mail.Read, Mail.ReadWrite

Solicitação HTTP

Para obter todas as mensagens na caixa de correio do usuário:

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

Para obter mensagens em uma pasta específica na caixa de correio do usuário:

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

Para obter todas as mensagens na caixa de correio do usuário que incluem uma menção do usuário:

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

Parâmetros de consulta opcionais

Este método dá suporte a Parâmetros de consulta OData para ajudar a personalizar a resposta.

Você pode usar o $filter parâmetro de consulta na propriedade mentionsPreview para obter as mensagens que mencionam o usuário conectado.

Uso de filtro e orderby na mesma consulta

Ao usar $filter e $orderby na mesma consulta para obter mensagens, lembre-se de especificar as propriedades das seguintes maneiras:

As propriedades que aparecem em $orderby também devem aparecer em $filter.
As propriedades que aparecem em $orderby estão na mesma ordem que em $filter.
As propriedades presentes em $orderby aparecem em $filter antes de qualquer propriedade que não esteja presente.

Ao não fazer isso, o seguinte erro surge:

Código de erro: InefficientFilter
Mensagem de erro: The restriction or sort order is too complex for this operation.

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	string	{token} de portador. Obrigatório.
Prefer: outlook.body-content-type	string	O formato das propriedades body e uniqueBody a serem retornadas. Os valores podem ser "text" ou "html". Se o cabeçalho não for especificado, as propriedades body e uniqueBody serão retornadas no formato HTML. Opcional.

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se tiver êxito, este método retornará um código 200 OK de resposta e uma coleção de objetos de mensagem no corpo da resposta.

Exemplos

Exemplo 1: Listar todas as mensagens

Solicitação

O primeiro exemplo obtém as 10 principais mensagens padrão na caixa de correio do usuário conectado. Ele usa $select para retornar um subconjunto das propriedades de cada mensagem na resposta.

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var messages = await graphClient.Me.Messages
    .Request()
    .Select("sender,subject")
    .GetAsync();

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


const options = {
    authProvider,
};

const client = Client.init(options);

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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/messages?$select=sender,subject"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphMessage *message = [[MSGraphMessage alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
    .buildRequest()
    .select("sender,subject")
    .get();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.MessagesRequestBuilderGetQueryParameters{
    Select: "sender,subject",
}
options := &msgraphsdk.MessagesRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
result, err := graphClient.Me().Messages().GetWithRequestConfigurationAndResponseHandler(options, nil)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


Import-Module Microsoft.Graph.Mail

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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Resposta

Este é um exemplo de resposta. Para obter a próxima página de mensagens, aplique a URL retornada em @odata.nextLink a uma solicitação GET subsequente.

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)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
      "id": "AAMkAGUAAAwTW09AAA=",
      "subject": "You have late tasks!",
      "sender": {
        "emailAddress": {
          "name": "Microsoft Planner",
          "address": "noreply@Planner.Office365.com"
        }
      }
    }
  ]
}

Exemplo 2: usar $filter para obter todas as mensagens que satisfazem uma condição específica

Solicitação

O próximo exemplo filtra todas as mensagens na caixa de correio do usuário conectado para aquelas que mencionam o usuário. Ele também usa $select para retornar um subconjunto das propriedades de cada mensagem na resposta.

O exemplo a seguir também incorpora a codificação de URL para os caracteres de espaço na cadeia de caracteres do parâmetro de consulta.

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var messages = await graphClient.Me.Messages
    .Request()
    .Filter("MentionsPreview/IsMentioned eq true")
    .Select("subject,sender,receivedDateTime,mentionsPreview")
    .GetAsync();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


const options = {
    authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
    .version('beta')
    .filter('MentionsPreview/IsMentioned eq true')
    .select('subject,sender,receivedDateTime,mentionsPreview')
    .get();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphMessage *message = [[MSGraphMessage alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
    .buildRequest()
    .filter("MentionsPreview/IsMentioned eq true")
    .select("subject,sender,receivedDateTime,mentionsPreview")
    .get();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.MessagesRequestBuilderGetQueryParameters{
    Filter: "MentionsPreview/IsMentioned%20eq%20true",
    Select: "Subject,Sender,ReceivedDateTime,MentionsPreview",
}
options := &msgraphsdk.MessagesRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
result, err := graphClient.Me().Messages().GetWithRequestConfigurationAndResponseHandler(options, nil)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "MentionsPreview/IsMentioned eq true" -Property "Subject,Sender,ReceivedDateTime,MentionsPreview"

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Resposta

Este é um exemplo de resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
  "@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":"Adele Vance",
          "address":"AdeleV@contoso.com"
        }
      },
      "mentionsPreview":{
        "isMentioned":true
      }
    }
  ]
}

Exemplo 3: usar o cabeçalho prefer para obter o corpo da mensagem e uniqueBody é o formato de texto

Solicitação

O terceiro exemplo mostra como usar um cabeçalho para obter as Prefer: outlook.body-content-type="text" propriedades body e uniqueBody de cada mensagem no formato de texto.

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var messages = await graphClient.Me.Messages
    .Request()
    .Header("Prefer","outlook.body-content-type=\"text\"")
    .Select("subject,body,bodyPreview,uniqueBody")
    .GetAsync();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


const options = {
    authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
    .version('beta')
    .header('Prefer','outlook.body-content-type="text"')
    .select('subject,body,bodyPreview,uniqueBody')
    .get();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/messages?$select=subject,body,bodyPreview,uniqueBody"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"outlook.body-content-type=\"text\"" forHTTPHeaderField:@"Prefer"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphMessage *message = [[MSGraphMessage alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "outlook.body-content-type=\"text\""));

MessageCollectionPage messages = graphClient.me().messages()
    .buildRequest( requestOptions )
    .select("subject,body,bodyPreview,uniqueBody")
    .get();

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.MessagesRequestBuilderGetQueryParameters{
    Select: "subject,body,bodyPreview,uniqueBody",
}
headers := map[string]string{
    "Prefer": "outlook.body-content-type="text""
}
options := &msgraphsdk.MessagesRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
    Headers: headers,
}
result, err := graphClient.Me().Messages().GetWithRequestConfigurationAndResponseHandler(options, nil)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.


Import-Module Microsoft.Graph.Mail

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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Resposta

Este é um exemplo de resposta.

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

{
  "@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"
      }
    }
  ]
}

Listar mensagens

Permissões

Solicitação HTTP

Parâmetros de consulta opcionais

Uso de filtro e orderby na mesma consulta

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: Listar todas as mensagens

Solicitação

Resposta

Exemplo 2: usar $filter para obter todas as mensagens que satisfazem uma condição específica

Solicitação

Resposta

Exemplo 3: usar o cabeçalho prefer para obter o corpo da mensagem e uniqueBody é o formato de texto

Solicitação

Resposta

Comentários