Répertorier des messages

  • Article

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

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

Voici un exemple qui 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/v1.0/me/messages?$select=sender,subject

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