Répertorier des messages

Article
10/30/2023

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Obtient les messages dans la boîte aux lettres de l’utilisateur connecté (y compris les dossiers d’éléments supprimés et de courrier basse priorité).

Selon la taille de la page et les données de la boîte aux lettres, l'obtention de messages à partir d'une boîte aux lettres peut entraîner des demandes multiples. La taille de page par défaut est de 10 messages. Utilisez $top pour personnaliser la taille de page, dans la plage de 1 et 1 000.

Pour améliorer le temps de réponse à l’opération, utilisez $select pour spécifier les propriétés exactes dont vous avez besoin. Consultez exemple 1 ci-dessous. Vous pouvez affiner les valeurs de $select et $top, en particulier lorsque vous devez utiliser une taille de page plus grande, car le renvoi d’une page avec des centaines de messages chacun avec une charge utile de réponse complète peut déclencher le délai d'attente de la passerelle(HTTP 504).

Pour obtenir la page suivante de messages, appliquez simplement l’URL entière retournée dans @odata.nextLink à la requête get-messages suivante. Cette URL inclut les paramètres de la requête que vous avez peut-être spécifiés dans la demande initiale.

N’essayez pas d’extraire la valeur $skip de l’URL @odata.nextLink pour manipuler des réponses. Cette API utilise la valeur $skip pour contrôler le nombre d’éléments qui sont passés dans boîte aux lettres de l’utilisateur pour renvoyer une page d’éléments de type de message. La valeur $skip peut donc être supérieure à la taille de la page. même dans la réponse initiale. Pour plus d’informations, voir Pagination des données Microsoft Graph dans votre application.

Vous pouvez filtrer sur les messages et obtenir uniquement ceux qui incluent un mention de l’utilisateur connecté. Un exemple est fourni ci-dessous. Par défaut, l’opération GET /me/messages ne retourne pas la propriété mentions . Utilisez le $expand paramètre de requête pour rechercher les détails de chaque mention dans un message.

Une application peut récupérer les messages du dossier de courrier d’un autre utilisateur dans deux cas :

Si l’application dispose des autorisations d’application ; ou
Si l’application a les autorisations déléguées adéquates d’un utilisateur et si un autre utilisateur a partagé un dossier de courrier avec cet utilisateur, ou s’il a accordé un accès délégué à cet utilisateur. Consultez les détails et un exemple.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global	Gouvernement des États-Unis L4	Us Government L5 (DOD)	Chine gérée par 21Vianet
✅	✅	✅	✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation	Autorisations avec privilèges minimum	Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire)	Mail.ReadBasic	Mail.ReadWrite, Mail.Read
Déléguée (compte Microsoft personnel)	Mail.ReadBasic	Mail.ReadWrite, Mail.Read
Application	Mail.ReadBasic.All	Mail.ReadWrite, Mail.Read

Requête HTTP

Pour obtenir tous les messages de la boîte aux lettres d’un utilisateur :

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

Pour obtenir les messages d’un dossier spécifique de la boîte aux lettres de l’utilisateur :

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

Pour obtenir tous les messages dans la boîte aux lettres de l’utilisateur qui incluent un mention de l’utilisateur :

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

Paramètres facultatifs de la requête

Cette méthode prend en charge les paramètres de requête OData pour vous aider à personnaliser la réponse.

Vous pouvez utiliser le $filter paramètre de requête sur la propriété mentionsPreview pour obtenir les messages qui mention l’utilisateur connecté.

Utilisation du filtre et d’orderby dans la même requête.

Lorsque vous utilisez à la fois $filter et $orderby, veillez à spécifier des propriétés comme suit :

Les propriétés qui apparaissent dans $orderby doivent également s'afficher dans $filter.
Les propriétés qui apparaissent dans $orderby sont dans le même ordre que dans $filter.
Les propriétés présentes dans $orderby s’affichent dans $filter avant les autres propriétés.

À défaut, l’erreur suivante apparaît :

Code d’erreur :InefficientFilter
Message d’erreur :The restriction or sort order is too complex for this operation.

En-têtes de demande

Nom	Type	Description
Autorisation	string	Porteur {token}. Obligatoire.
Prefer: outlook.body-content-type	string	Format auquel les propriétés body et uniqueBody sont renvoyées. Les valeurs peuvent être au format « texte » ou « html ». Si l’en-tête n’est pas spécifié, les propriétés body et uniqueBody sont renvoyées au format HTML. Facultatif.

Corps de la demande

N’indiquez pas le corps de la demande pour cette méthode.

Réponse

Si elle réussit, cette méthode renvoie un code de réponse et une 200 OK collection d’objets de message dans le corps de la réponse.

Exemples

Exemple 1 : répertorier tous les messages

Demande

Le premier exemple obtient les 10 premiers messages par défaut dans la boîte aux lettres de l’utilisateur connecté. Il utilise $select pour renvoyer un sous-ensemble des propriétés de chaque message dans la réponse.

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

Microsoft Graph SDK utilisent la version v1.0 de l’API par défaut et ne prennent pas en charge tous les types, propriétés et API disponibles dans la version bêta. Pour plus d’informations sur l’accès à l’API bêta avec le SDK, consultez Utiliser les kits de développement logiciel (SDK) Microsoft Graph avec l’API bêta.

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users messages list --user-id {user-id} --select "sender,subject"

Importante



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Importante


// 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


const options = {
	authProvider,
};

const client = Client.init(options);

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

Importante


<?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();

Importante


Import-Module Microsoft.Graph.Beta.Mail

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

Importante


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		select = ["sender","subject"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

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

Importante

Réponse

L’exemple suivant illustre la réponse. Pour obtenir la page suivante de messages, appliquez l’URL renvoyée dans @odata.nextLink à une requête GET suivante.

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

Exemple 2 : utiliser $filter pour obtenir tous les messages répondant à une condition spécifique

Demande

L’exemple suivant filtre tous les messages de la boîte aux lettres de l’utilisateur connecté pour ceux qui mention l’utilisateur. Il utilise $select également pour retourner un sous-ensemble des propriétés de chaque message dans la réponse.

L’exemple suivant incorpore également l’encodage d’URL pour les caractères d’espace dans la chaîne de paramètre de requête.

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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users messages list --user-id {user-id} --filter "MentionsPreview/IsMentioned eq true" --select "Subject,Sender,ReceivedDateTime,MentionsPreview"

Importante



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "MentionsPreview/IsMentioned eq true"

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Select: [] string {"Subject","Sender","ReceivedDateTime","MentionsPreview"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Importante


// 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


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


<?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->filter = "MentionsPreview/IsMentioned eq true";
$queryParameters->select = ["Subject","Sender","ReceivedDateTime","MentionsPreview"];
$requestConfiguration->queryParameters = $queryParameters;


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

Importante


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


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		filter = "MentionsPreview/IsMentioned eq true",
		select = ["Subject","Sender","ReceivedDateTime","MentionsPreview"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

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

Importante

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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
      }
    }
  ]
}

Exemple 3 : utiliser l’en-tête prefer pour obtenir le corps du message et uniqueBody est au format texte

Demande

Le troisième exemple montre comment utiliser un Prefer: outlook.body-content-type="text" en-tête pour obtenir les propriétés body et uniqueBody de chaque message au format texte.

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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users messages list --user-id {user-id} --select "subject,body,bodyPreview,uniqueBody"

Importante



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Importante


// 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


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


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\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


Import-Module Microsoft.Graph.Beta.Mail

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

Importante


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		select = ["subject","body","bodyPreview","uniqueBody"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
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

Réponse

L’exemple suivant illustre la réponse.

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

Répertorier des messages

Autorisations

Requête HTTP

Paramètres facultatifs de la requête

Utilisation du filtre et d’orderby dans la même requête.

En-têtes de demande

Corps de la demande

Réponse

Exemples

Exemple 1 : répertorier tous les messages

Demande

Réponse

Exemple 2 : utiliser $filter pour obtenir tous les messages répondant à une condition spécifique

Demande

Réponse

Exemple 3 : utiliser l’en-tête prefer pour obtenir le corps du message et uniqueBody est au format texte

Demande

Réponse

Commentaires

Commentaires

Ressources supplémentaires