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 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.
Pode filtrar as mensagens e obter apenas as que incluem uma menção ao utilizador com sessão iniciada. Veja um exemplo abaixo.
Por predefinição, a GET /me/messages operação não devolve a propriedade menções . Utilize o $expand parâmetro de consulta para encontrar detalhes de cada menção numa 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. Confira detalhes e um exemplo.
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
Para obter todas as mensagens na caixa de correio do utilizador que incluem uma menção ao utilizador:
GET /me/messages?$filter=mentionsPreview/isMentioned eq true
GET /users/{id | userPrincipalName}/messages?$filter=mentionsPreview/isMentioned eq true
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 for bem-sucedido, este método devolve um código de resposta e uma 200 OK 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 predefinidas na caixa de correio do utilizador com sessão iniciada. 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
// 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" };
});
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
mgc-beta users messages list --user-id {user-id} --select "sender,subject"
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-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)
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
// 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"};
});
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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();
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Property "sender,subject"
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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)
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
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.
Exemplo 2: Utilize $filter para obter todas as mensagens que satisfaçam uma condição específica
Solicitação
O exemplo seguinte filtra todas as mensagens na caixa de correio do utilizador com sessão iniciada para as que mencionam o utilizador. Também utiliza $select para devolver um subconjunto das propriedades de cada mensagem na resposta.
O exemplo seguinte também incorpora a codificação de URL para os carateres de espaço na cadeia do parâmetro de consulta.
GET https://graph.microsoft.com/beta/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview
// 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.Filter = "MentionsPreview/IsMentioned eq true";
requestConfiguration.QueryParameters.Select = new string []{ "Subject","Sender","ReceivedDateTime","MentionsPreview" };
});
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestFilter := "MentionsPreview/IsMentioned eq true"
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Select: [] string {"Subject","Sender","ReceivedDateTime","MentionsPreview"},
}
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)
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
// 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.filter = "MentionsPreview/IsMentioned eq true";
requestConfiguration.queryParameters.select = new String []{"Subject", "Sender", "ReceivedDateTime", "MentionsPreview"};
});
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "MentionsPreview/IsMentioned eq true";
$queryParameters->select = ["Subject","Sender","ReceivedDateTime","MentionsPreview"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Filter "MentionsPreview/IsMentioned eq true" -Property "Subject,Sender,ReceivedDateTime,MentionsPreview"
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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(
filter = "MentionsPreview/IsMentioned eq true",
select = ["Subject","Sender","ReceivedDateTime","MentionsPreview"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Exemplo 3: utilize o cabeçalho preferencial para obter o corpo da mensagem e uniqueBody é o formato de texto
Solicitação
O terceiro exemplo mostra como utilizar um Prefer: outlook.body-content-type="text" cabeçalho para obter as propriedades do corpo 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"
// 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 []{ "subject","body","bodyPreview","uniqueBody" };
requestConfiguration.Headers.Add("Prefer", "outlook.body-content-type=\"text\"");
});
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
mgc-beta users messages list --user-id {user-id} --select "subject,body,bodyPreview,uniqueBody"
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "outlook.body-content-type=\"text\"")
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"subject","body","bodyPreview","uniqueBody"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
Headers: headers,
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)
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
// 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 []{"subject", "body", "bodyPreview", "uniqueBody"};
requestConfiguration.headers.add("Prefer", "outlook.body-content-type=\"text\"");
});
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$headers = [
'Prefer' => 'outlook.body-content-type="text"',
];
$requestConfiguration->headers = $headers;
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["subject","body","bodyPreview","uniqueBody"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Property "subject,body,bodyPreview,uniqueBody"
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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 = ["subject","body","bodyPreview","uniqueBody"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("Prefer", "outlook.body-content-type=\"text\"")
result = await graph_client.me.messages.get(request_configuration = request_configuration)
Importante
Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem 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.
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"
}
}
]
}