Partager via


Répertorier les mailFolders

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 .

Obtenir la collection de dossiers de courrier figurant directement sous le dossier racine de l’utilisateur connecté. La collection renvoyée inclut tous les dossiers de recherche de courrier directement sous la racine.

Par défaut, cette opération ne renvoie pas les dossiers cachés. Utilisez un paramètre includeHiddenFolders de requête pour les inclure dans la réponse. Cette opération ne retourne pas tous les dossiers de courrier d’une boîte aux lettres, mais uniquement les dossiers enfants du dossier racine. Pour renvoyer tous les dossiers de courrier dans une boîte aux lettres, chaque dossier enfant doit être parcouru séparément.

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 dossiers de courrier dans le dossier racine de la boîte aux lettres de l’utilisateur spécifié, à l’exception de ceux qui sont masqués :

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

Pour inclure les dossiers de courrier masqués dans la réponse :

GET /me/mailFolders/?includeHiddenFolders=true
GET /users/{id | userPrincipalName}/mailFolders/?includeHiddenFolders=true

Paramètres facultatifs de la requête

Pour renvoyer une liste de tous les mailFolders, y compris ceux qui sont masqués (leur propriété isHidden est true), dans l’URL de la requête, définissez le paramètre de requête includeHiddenFolders sur true, comme indiqué dans la section Requête HTTP.

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

En-têtes de demande

En-tête Valeur
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.

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 200 OK code de réponse et la collection d’objets mailFolder dans le corps de la réponse.

Exemples

Exemple 1 : répertorier les dossiers de courrier de la boîte aux lettres de l’utilisateur connecté

Cet exemple inclut un objet mailSearchFolder dans la réponse. Le dossier de recherche de courrier est un dossier enfant de la boîte de réception avec comme nom d’affichage « Synthèses hebdomadaires ».

Demande

L’exemple suivant illustre une demande.

GET https://graph.microsoft.com/beta/me/mailFolders

Réponse

Voici un exemple de réponse, qui inclut un dossier mailSearchFolder qui est un dossier enfant sous la boîte de réception.

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#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders",
    "value": [
        {
            "id": "AQMkADYAAAIBXQAAAA==",
            "displayName": "Archive",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "archive",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBFQAAAA==",
            "displayName": "Conversation History",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 1,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "conversationhistory",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBCgAAAA==",
            "displayName": "Deleted Items",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "deleteditems",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBDwAAAA==",
            "displayName": "Drafts",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "drafts",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBDAAAAA==",
            "displayName": "Inbox",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 1,
            "unreadItemCount": 70,
            "totalItemCount": 71,
            "wellKnownName": "inbox",
            "isHidden": false
        },
        {
            "@odata.type": "#microsoft.graph.mailSearchFolder",
            "id": "AAMkADYRAAAZg1yTAAA=",
            "displayName": "Weekly digests",
            "parentFolderId": "AQMkADYAAAIBDAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 4,
            "totalItemCount": 5,
            "wellKnownName": null,
            "isHidden": false,
            "isSupported": true,
            "filterQuery": "contains(subject, 'weekly digest')"
        },
        {
            "id": "AQMkADYAAAIBGQAAAA==",
            "displayName": "Junk Email",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "junkemail",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBCwAAAA==",
            "displayName": "Outbox",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "outbox",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBCQAAAA==",
            "displayName": "Sent Items",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "sentitems",
            "isHidden": false
        }
    ]
}

Conseil

Si une collection dépasse la taille de page par défaut (10 éléments), la propriété @odata.nextLink est retournée dans la réponse pour indiquer que d’autres éléments sont disponibles et fournir l’URL de la demande pour la page suivante d’éléments.

Vous pouvez contrôler le format de page par le biais des paramètres de chaîne de requête facultatifs

Exemple 2 : Inclure les dossiers masqués de la boîte aux lettres de l’utilisateur connecté

Cet exemple utilise le paramètre de includeHiddenFolders requête pour obtenir une liste de dossiers de courrier, y compris les dossiers de courrier masqués. La réponse inclut le dossier « Courrier pêle-mêle » pour lequel isHidden est défini sur true.

Demande

GET https://graph.microsoft.com/beta/me/mailFolders/?includeHiddenFolders=true

Réponse

L’exemple suivant illustre la réponse.

Remarque : L’objet de réponse illustré ici est raccourci pour plus de lisibilité et n’inclut pas tous les dossiers par défaut d’une boîte aux lettres utilisateur.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders",
    "value": [
        {
            "id": "AAMkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWAAA=",
            "displayName": "Clutter",
            "parentFolderId": "AAMkADg3NTY5MDg4LWMzYmQtEIAAA=",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": null,
            "isHidden": true
        },
        {
            "id": "AAMkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWAAA=",
            "displayName": "Conversation History",
            "parentFolderId": "AAMkADg3NTY5MDg4LWMzYmQtEIAAA=",
            "childFolderCount": 1,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "conversationhistory",
            "isHidden": false
        }
    ]
}