Répertorier des messages

Espace de noms: microsoft.graph

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.

Actuellement, cette opération renvoie les corps de messages uniquement au format HTML.

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 qu’un autre utilisateur a partagé un dossier de courrier avec cet utilisateur, ou, a accordé un accès délégué à cet utilisateur. Consultez les détails et un exemple.

Remarque : le fait que cette opération inclue les messages de conversation Microsoft Teams dans sa réponse est un problème connu.

Autorisations

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Déléguée (compte Microsoft personnel) Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Application Mail.ReadBasic.All, Mail.Read, Mail.ReadWrite

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

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.

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 :

  1. Les propriétés qui apparaissent dans $orderby doivent également s'afficher dans $filter.
  2. Les propriétés qui apparaissent dans $orderby sont dans le même ordre que dans $filter.
  3. 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 200 OK et la collection d’objets Message dans le corps de la réponse.

Exemples

Exemple 1 : répertorier tous les messages

Demande

Cet exemple obtient les 10 premiers messages par défaut de 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/v1.0/me/messages?$select=sender,subject

Réponse

Voici un exemple de 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/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"
                }
            }
        }
    ]
}