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 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 do 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.
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
Para obter todas as mensagens na caixa de correio do utilizador que incluem uma menção do utilizador:
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.
Pode utilizar o $filter parâmetro de consulta na propriedade mentionsPreview para obter as mensagens que menção o utilizador com sessão iniciada.
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.
| 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 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" };
});
// 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)
// 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"};
});
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.version('beta')
.select('sender,subject')
.get();
<?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();
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Property "sender,subject"
# 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)
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/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: 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 menção 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" };
});
// 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)
// 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"};
});
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();
<?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();
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"
# 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)
Resposta
O exemplo a seguir mostra a 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: 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\"");
});
// 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)
// 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\"");
});
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();
<?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();
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Property "subject,body,bodyPreview,uniqueBody"
# 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)
Resposta
O exemplo a seguir mostra a 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"
}
}
]
}