mailFolder resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

A mail folder in a user's mailbox, such as Inbox and Drafts. Mail folders can contain messages, other Outlook items, and child mail folders.

This resource supports using delta query to track incremental additions, deletions, and updates, by providing a delta function.

Well-known folder names

Outlook creates certain folders for users by default. Instead of using the corresponding folder id value, for convenience, you can use the well-known folder names from the table below when accessing these folders. For example, you can get the Drafts folder using its well-known name with the following query.

GET /me/mailFolders/drafts

Well-known names work regardless of the locale of the user's mailbox, so the above query will always return the user's Drafts folder regardless of its name.

Well-known folder name Description
archive The archive folder messages are sent to when using the One_Click Archive feature in Outlook clients that support it. Note: this isn't the same as the Archive Mailbox feature of Exchange online.
clutter The clutter folder low-priority messages are moved to when using the Clutter feature.
conflicts The folder that contains conflicting items in the mailbox.
conversationhistory The folder where Skype saves IM conversations (if Skype is configured to do so).
deleteditems The folder items are moved to when they are deleted.
drafts The folder that contains unsent messages.
inbox The inbox folder.
junkemail The junk email folder.
localfailures The folder that contains items that exist on the local client but couldn't be uploaded to the server.
msgfolderroot The "Top of Information Store" folder. This folder is the parent folder for folders that are displayed in normal mail clients, such as the inbox.
outbox The outbox folder.
recoverableitemsdeletions The folder that contains soft-deleted items: deleted either from the Deleted Items folder, or by pressing shift+delete in Outlook. This folder isn't visible in any Outlook email client, but end users can interact with it through the Recover Deleted Items from Server feature in Outlook or Outlook on the web.
scheduled The folder that contains messages that are scheduled to reappear in the inbox using the Schedule feature in Outlook for iOS.
searchfolders The parent folder for all search folders defined in the user's mailbox.
sentitems The sent items folder.
serverfailures The folder that contains items that exist on the server but couldn't be synchronized to the local client.
syncissues The folder that contains synchronization logs created by Outlook.

Methods

Method Return Type Description
List mail search folders mailFolder collection Get all the mail folders in the specified user's mailbox, including any mail search folders.
Get mail search folder mailFolder Read properties and relationships of mailFolder object.
Create mail folder mailFolder Create a new mail folder in the root folder of the user's mailbox.
List child folders mailFolder collection Get the folder collection under the specified folder. You can use the .../me/MailFolders shortcut to get the top-level folder collection and navigate to another folder.
Create child folder mailFolder Create a new mailFolder under the current one by posting to the childFolders collection.
Create message in folder message Create a new message in the current mailFolder by posting to the messages collection.
List messages in folder message collection Get all the messages in the signed-in user's mailbox, or those messages in a specified folder in the mailbox.
Update mail folder mailFolder Update the specified mailFolder object.
Delete mail search folder None Delete the specified mailFolder object.
Copy mail folder mailFolder Copy a mailFolder and its contents to another mailFolder.
Get folder delta mailFolder collection Get a set of mail folders that have been added, deleted, or removed from the user's mailbox.
Move mail folder mailFolder Move a mailFolder and its contents to another mailFolder.
Permanently delete None Permanently delete a mail folder and remove its items from the user's mailbox.
Extended properties
Create single-value property mailFolder Create one or more single-value extended properties in a new or existing mailFolder.
Get single-value property mailFolder Get mailFolders that contain a single-value extended property by using $expand or $filter.
Create multi-value property mailFolder Create one or more multi-value extended properties in a new or existing mailFolder.
Get multi-value property mailFolder Get a mailFolder that contains a multi-value extended property by using $expand.

Properties

Property Type Description
childFolderCount Int32 The number of immediate child mailFolders in the current mailFolder.
displayName String The mailFolder's display name.
id String The mailFolder's unique identifier.
isHidden Boolean Indicates whether the mailFolder is hidden. This property can be set only when creating the folder. Find more information in Hidden mail folders.
parentFolderId String The unique identifier for the mailFolder's parent mailFolder.
totalItemCount Int32 The number of items in the mailFolder.
unreadItemCount Int32 The number of items in the mailFolder marked as unread.
wellKnownName String The well-known folder name for the folder. The possible values are listed above. This property is only set for default folders created by Outlook. For other folders, this property is null.

Access item counts efficiently

The TotalItemCount and UnreadItemCount properties of a folder allow you to conveniently compute the number of read items in the folder. They let you avoid queries like the following that can incur significant latency:

https://outlook.office.com/api/beta/me/folders/inbox/messages?$count=true&$filter=isread%20eq%20false

Mail folders in Outlook can contain more than one type of items, for example, the Inbox can contain meeting request items that are distinct from mail items. TotalItemCount and UnreadItemCount include items in a mail folder irrespective of their item types.

Hidden mail folders

The default value of the isHidden property is false. You can set isHidden only once when creating the mailFolder. You can't update the property using a PATCH operation. To change the isHidden property of a folder, delete the existing folder and create a new one with the desired value.

Hidden mail folders support all operations that are supported by a regular mail folder.

By default, listing mailFolders returns only mail folders that aren't hidden. To include hidden mail folders in the response, use the query parameter includeHiddenFolders=true. Then use the isHidden property to identify whether a mail folder is hidden.

Relationships

Relationship Type Description
childFolders MailFolder collection The collection of child folders in the mailFolder.
messageRules messageRule collection The collection of rules that apply to the user's Inbox folder.
messages Message collection The collection of messages in the mailFolder.
multiValueExtendedProperties multiValueLegacyExtendedProperty collection The collection of multi-value extended properties defined for the mailFolder. Read-only. Nullable.
singleValueExtendedProperties singleValueLegacyExtendedProperty collection The collection of single-value extended properties defined for the mailFolder. Read-only. Nullable.

JSON representation

The following JSON representation shows the resource type.

{
  "childFolderCount": 1024,
  "displayName": "string",
  "id": "string (identifier)",
  "parentFolderId": "string",
  "totalItemCount": 1024,
  "unreadItemCount": 1024,
  "wellKnownName": "string",
  "isHidden": false,
  "childFolders": [ { "@odata.type": "microsoft.graph.mailFolder" } ],
  "messageRules": [ { "@odata.type": "microsoft.graph.messageRule" } ],
  "messages": [ { "@odata.type": "microsoft.graph.message" } ],
  "multiValueExtendedProperties": [ { "@odata.type": "microsoft.graph.multiValueLegacyExtendedProperty" }],
  "singleValueExtendedProperties": [ { "@odata.type": "microsoft.graph.singleValueLegacyExtendedProperty" }]
}