--- title: "Create child folder" method: POST path: "/me/mailFolders/{mailFolderId}/childFolders" tags: ["me.mailFolder"] --- # Create child folder `POST /me/mailFolders/{mailFolderId}/childFolders` ## Request - Base URL: `https://graph.microsoft.com/v1.0` - URL: `https://graph.microsoft.com/v1.0/me/mailFolders/{mailFolderId}/childFolders` - Auth: OAuth 2 - Authorization code: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` - Client credentials - Token URL: `https://login.microsoftonline.com/common/oauth2/v2.0/token` scopes: `Mail.Read`, `Mail.ReadWrite`, `Mail.Send` - TypeScript: (a function with typed inputs; its response is checked against the schema) Use this API to create a new child mailFolder. If you intend a new folder to be hidden, you must set the isHidden property to true on creation. To create a mail search folder as a child, set the '@odata.type' property to '#microsoft.graph.mailSearchFolder'. ## Request body - MicrosoftGraphMailFolder - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `childFolderCount` number, nullable: The number of immediate child mailFolders in the current mailFolder - `parentFolderId` string, nullable: The unique identifier for the mailFolder's parent mailFolder - `displayName` string, nullable: The mailFolder's display name - `childFolders` MicrosoftGraphMailFolder[]: The collection of child folders in the mailFolder - `messages` MicrosoftGraphMessage[]: The collection of messages in the mailFolder - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `changeKey` string, nullable: Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only - `lastModifiedDateTime` string, date-time, nullable: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z - `createdDateTime` string, date-time, nullable: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z - `categories` string[]: The categories associated with the item - `flag` union: Indicates the status, start date, due date, or completion date for the message - MicrosoftGraphFollowupFlag - `startDateTime` union: The date and time that the follow-up is to begin - MicrosoftGraphDateTimeTimeZone - `dateTime` string: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000) - `@odata.type` string - `timeZone` string, nullable: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values - object, nullable - `dueDateTime` union: The date and time that the follow-up is to be finished. Note: To set the due date, you must also specify the startDateTime; otherwise, you get a 400 Bad Request response - MicrosoftGraphDateTimeTimeZone - `dateTime` string: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000) - `@odata.type` string - `timeZone` string, nullable: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values - object, nullable - `flagStatus` union: The status for follow-up for an item. Possible values are notFlagged, complete, and flagged - 'notFlagged' | 'complete' | 'flagged' - object, nullable - `@odata.type` string - `completedDateTime` union: The date and time that the follow-up was finished - MicrosoftGraphDateTimeTimeZone - `dateTime` string: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000) - `@odata.type` string - `timeZone` string, nullable: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values - object, nullable - object, nullable - `attachments` MicrosoftGraphAttachment[]: The fileAttachment and itemAttachment attachments for the message - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `lastModifiedDateTime` string, date-time, nullable: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z - `size` number: The length of the attachment in bytes - `name` string, nullable: The attachment's file name - `isInline` boolean: true if the attachment is an inline attachment; otherwise, false - `contentType` string, nullable: The MIME type - `contentBytes` string, base64url, nullable: The base64-encoded contents of the file attachment. Required only for file attachments - `parentFolderId` string, nullable: The unique identifier for the message's parent mailFolder - `importance` union: The importance of the message. The possible values are: low, normal, and high - 'low' | 'normal' | 'high' - object, nullable - `subject` string, nullable: The subject of the message - `webLink` string, nullable: The URL to open the message in Outlook on the web - `isDraft` boolean, nullable: Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet - `isRead` boolean, nullable: Indicates whether the message has been read - `bodyPreview` string, nullable: The first 255 characters of the message body. It is in text format - `body` union: The body of the message. It can be in HTML or text format. Find out about safe HTML in a message body - MicrosoftGraphItemBody - `@odata.type` string - `contentType` union: The type of the content. Possible values are text and html - 'text' | 'html' - object, nullable - `content` string, nullable: The content of the item - object, nullable - `inferenceClassification` union: The classification of the message for the user, based on inferred relevance or importance, or on an explicit override - 'focused' | 'other' - object, nullable - `internetMessageId` string, nullable: The message ID in the format specified by RFC2822 - `toRecipients` MicrosoftGraphRecipient[]: The To: recipients for the message - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `isReadReceiptRequested` boolean, nullable: Indicates whether a read receipt is requested for the message - `from` union: The owner of the mailbox from which the message is sent. In most cases, this value is the same as the sender property, except for sharing or delegation scenarios - MicrosoftGraphRecipient - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - object, nullable - `uniqueBody` union: The part of the body of the message that is unique to the current message. uniqueBody is not returned by default but can be retrieved with $select=uniqueBody - MicrosoftGraphItemBody - `@odata.type` string - `contentType` union: The type of the content. Possible values are text and html - 'text' | 'html' - object, nullable - `content` string, nullable: The content of the item - object, nullable - `hasAttachments` boolean, nullable: Indicates whether the message has attachments. This property doesn't include inline attachments, so if a message contains only inline attachments, this property is false - `sentDateTime` string, date-time, nullable: The date and time the message was sent. The date and time information uses ISO 8601 format and is always in UTC time - `conversationIndex` string, base64url, nullable: Indicates the position of the message within the conversation - `conversationId` string, nullable: The ID of the conversation the email belongs to - `internetMessageHeaders` MicrosoftGraphInternetMessageHeader[]: A collection of message headers defined by RFC5322. The set includes message headers indicating the network path taken by a message from the sender to the recipient - `@odata.type` string - `name` string, nullable: Represents the key in a key-value pair - `value` string, nullable: The value in a key-value pair - `receivedDateTime` string, date-time, nullable: The date and time the message was received. The date and time information uses ISO 8601 format and is always in UTC time - `extensions` MicrosoftGraphExtension[]: The collection of open extensions defined for the message. Nullable - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `sender` union: The account that is used to generate the message. In most cases, this value is the same as the from property - MicrosoftGraphRecipient - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - object, nullable - `bccRecipients` MicrosoftGraphRecipient[]: The Bcc: recipients for the message - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `ccRecipients` MicrosoftGraphRecipient[]: The Cc: recipients for the message - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `isDeliveryReceiptRequested` boolean, nullable: Indicates whether a read receipt is requested for the message - `replyTo` MicrosoftGraphRecipient[]: The email addresses to use when replying - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `unreadItemCount` number, nullable: The number of items in the mailFolder marked as unread - `isHidden` boolean, nullable: Indicates whether the mailFolder is hidden. This property can be set only when creating the folder - `totalItemCount` number, nullable: The number of items in the mailFolder ## Response `2XX` Created child mail folder - MicrosoftGraphMailFolder - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `childFolderCount` number, nullable: The number of immediate child mailFolders in the current mailFolder - `parentFolderId` string, nullable: The unique identifier for the mailFolder's parent mailFolder - `displayName` string, nullable: The mailFolder's display name - `childFolders` MicrosoftGraphMailFolder[]: The collection of child folders in the mailFolder - `messages` MicrosoftGraphMessage[]: The collection of messages in the mailFolder - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `changeKey` string, nullable: Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only - `lastModifiedDateTime` string, date-time, nullable: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z - `createdDateTime` string, date-time, nullable: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z - `categories` string[]: The categories associated with the item - `flag` union: Indicates the status, start date, due date, or completion date for the message - MicrosoftGraphFollowupFlag - `startDateTime` union: The date and time that the follow-up is to begin - MicrosoftGraphDateTimeTimeZone - `dateTime` string: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000) - `@odata.type` string - `timeZone` string, nullable: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values - object, nullable - `dueDateTime` union: The date and time that the follow-up is to be finished. Note: To set the due date, you must also specify the startDateTime; otherwise, you get a 400 Bad Request response - MicrosoftGraphDateTimeTimeZone - `dateTime` string: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000) - `@odata.type` string - `timeZone` string, nullable: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values - object, nullable - `flagStatus` union: The status for follow-up for an item. Possible values are notFlagged, complete, and flagged - 'notFlagged' | 'complete' | 'flagged' - object, nullable - `@odata.type` string - `completedDateTime` union: The date and time that the follow-up was finished - MicrosoftGraphDateTimeTimeZone - `dateTime` string: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000) - `@odata.type` string - `timeZone` string, nullable: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values - object, nullable - object, nullable - `attachments` MicrosoftGraphAttachment[]: The fileAttachment and itemAttachment attachments for the message - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `lastModifiedDateTime` string, date-time, nullable: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z - `size` number: The length of the attachment in bytes - `name` string, nullable: The attachment's file name - `isInline` boolean: true if the attachment is an inline attachment; otherwise, false - `contentType` string, nullable: The MIME type - `contentBytes` string, base64url, nullable: The base64-encoded contents of the file attachment. Required only for file attachments - `parentFolderId` string, nullable: The unique identifier for the message's parent mailFolder - `importance` union: The importance of the message. The possible values are: low, normal, and high - 'low' | 'normal' | 'high' - object, nullable - `subject` string, nullable: The subject of the message - `webLink` string, nullable: The URL to open the message in Outlook on the web - `isDraft` boolean, nullable: Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet - `isRead` boolean, nullable: Indicates whether the message has been read - `bodyPreview` string, nullable: The first 255 characters of the message body. It is in text format - `body` union: The body of the message. It can be in HTML or text format. Find out about safe HTML in a message body - MicrosoftGraphItemBody - `@odata.type` string - `contentType` union: The type of the content. Possible values are text and html - 'text' | 'html' - object, nullable - `content` string, nullable: The content of the item - object, nullable - `inferenceClassification` union: The classification of the message for the user, based on inferred relevance or importance, or on an explicit override - 'focused' | 'other' - object, nullable - `internetMessageId` string, nullable: The message ID in the format specified by RFC2822 - `toRecipients` MicrosoftGraphRecipient[]: The To: recipients for the message - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `isReadReceiptRequested` boolean, nullable: Indicates whether a read receipt is requested for the message - `from` union: The owner of the mailbox from which the message is sent. In most cases, this value is the same as the sender property, except for sharing or delegation scenarios - MicrosoftGraphRecipient - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - object, nullable - `uniqueBody` union: The part of the body of the message that is unique to the current message. uniqueBody is not returned by default but can be retrieved with $select=uniqueBody - MicrosoftGraphItemBody - `@odata.type` string - `contentType` union: The type of the content. Possible values are text and html - 'text' | 'html' - object, nullable - `content` string, nullable: The content of the item - object, nullable - `hasAttachments` boolean, nullable: Indicates whether the message has attachments. This property doesn't include inline attachments, so if a message contains only inline attachments, this property is false - `sentDateTime` string, date-time, nullable: The date and time the message was sent. The date and time information uses ISO 8601 format and is always in UTC time - `conversationIndex` string, base64url, nullable: Indicates the position of the message within the conversation - `conversationId` string, nullable: The ID of the conversation the email belongs to - `internetMessageHeaders` MicrosoftGraphInternetMessageHeader[]: A collection of message headers defined by RFC5322. The set includes message headers indicating the network path taken by a message from the sender to the recipient - `@odata.type` string - `name` string, nullable: Represents the key in a key-value pair - `value` string, nullable: The value in a key-value pair - `receivedDateTime` string, date-time, nullable: The date and time the message was received. The date and time information uses ISO 8601 format and is always in UTC time - `extensions` MicrosoftGraphExtension[]: The collection of open extensions defined for the message. Nullable - `@odata.type` string - `id` string: The unique identifier for an entity. Read-only - `sender` union: The account that is used to generate the message. In most cases, this value is the same as the from property - MicrosoftGraphRecipient - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - object, nullable - `bccRecipients` MicrosoftGraphRecipient[]: The Bcc: recipients for the message - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `ccRecipients` MicrosoftGraphRecipient[]: The Cc: recipients for the message - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `isDeliveryReceiptRequested` boolean, nullable: Indicates whether a read receipt is requested for the message - `replyTo` MicrosoftGraphRecipient[]: The email addresses to use when replying - `emailAddress` union: The recipient's email address - MicrosoftGraphEmailAddress - `address` string, nullable: The email address of the person or entity - `@odata.type` string - `name` string, nullable: The display name of the person or entity - object, nullable - `@odata.type` string - `unreadItemCount` number, nullable: The number of items in the mailFolder marked as unread - `isHidden` boolean, nullable: Indicates whether the mailFolder is hidden. This property can be set only when creating the folder - `totalItemCount` number, nullable: The number of items in the mailFolder ## Other responses - `4XX`: error - `5XX`: error ## Changes - **2026-07-17** `af62694b9f2d`: 2 info - added the new optional request property `allOf[subschema #2: mailFolder]/messages/items/allOf[subschema #2: message]/attachments/items/allOf[subschema #2: attachment]/contentBytes` - added the optional property `allOf[subschema #2: mailFolder]/messages/items/allOf[subschema #2: message]/attachments/items/allOf[subschema #2: attachment]/contentBytes` to the response with the `2XX` status - **2026-05-28** `354d90657cdd`: 1 info - api operation id `me.mailFolders.CreateChildFolders` removed and replaced with `createChildFolder` - …earlier changes not shown [Operation history](https://skmtc.dev/ballerina-platform/apis/microsoft-graph-mail-api/changes/me/mailFolders/:mailFolderId/childFolders/post.md) --- [API](https://skmtc.dev/ballerina-platform/apis/microsoft-graph-mail-api.md) - [All operations](https://skmtc.dev/ballerina-platform/apis/microsoft-graph-mail-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ballerina-platform/apis/microsoft-graph-mail-api/revisions/af62694b9f2d?raw)