Compartilhar via


Listar mensagens

Namespace: microsoft.graph

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.

No momento, essa operação retorna corpos de mensagens somente no formato HTML.

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. Confira detalhes e um exemplo.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

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

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

Parâmetros de consulta opcionais

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

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:

  1. As propriedades que aparecem em $orderby também devem aparecer em $filter.
  2. As propriedades que aparecem em $orderby estão na mesma ordem que em $filter.
  3. 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. Saiba mais sobre autenticação e autorização.
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 bem-sucedido, este método retorna um código de resposta 200 OK e uma coleção de objetos Message no corpo da resposta.

Exemplos

Exemplo 1: Listar todas as mensagens

Solicitação

A seguir, é mostrado um exemplo que 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/v1.0/me/messages?$select=sender,subject

Resposta

O exemplo a seguir mostra a 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/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"
                }
            }
        }
    ]
}