Can we specify a target mailbox folder while using Microsoft Graph sendMail API?

Question

We are using the POST /users/{id}/sendMail endpoint in Microsoft Graph to send emails programmatically.

Our requirement is to deliver certain system-generated emails (e.g., voicemail notifications) directly into a specific mailbox folder (for example, a custom folder like “Voicemail”) instead of the default Inbox.

Is there any supported way to specify the destination folder as part of the sendMail request?

For example:

Can we pass a folder ID in the request body?

Is there any header or parameter that allows direct delivery into a specific folder?

Or is the only supported approach to send the mail normally and then move it using /messages/{id}/move?

We are trying to avoid creating individual inbox rules for a large number of mailboxes, so we are looking for an API-based or centralized solution.

Any guidance on best practices for this scenario would be appreciated.

Answer 1

Hi Surekha Yeddula,

Thank you for posting your question in the Microsoft Q&A forum.

After researching, the behavior is as Q&A Assist mentioned: the sendMail API does not support specifying a target mailbox folder.

Besides the multi-step workaround (send first, then locate/move), you may consider a shorter alternative if all recipient mailboxes are internal within the same tenant and you’re able to manage those mailboxes via Microsoft Graph: you can create a message item directly in a specific folder.

That said, it’s important to clarify the tradeoff: this approach creates a message item in the mailbox folder rather than delivering a message through the normal mail transport pipeline. Because of that, Microsoft documentation does not state or guarantee it will trigger the same “new mail delivered” push/toast notification behavior as a real inbound email.

However, it can still appear as unread in that folder if you ensure the message is marked unread (for example via the message’s isRead property), and the folder has an unreadItemCount concept that Outlook clients use to show unread counts when the user views that folder.

Hope this helps.

---

If the answer is helpful, please click "Accept Answer" and kindly upvote it. If you have extra questions about this answer, please click "Comment".         

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.

Answer 2

The sendMail API does not support specifying a target mailbox folder. It always delivers to the mailbox (and, for the sender, creates the item in Sent Items) according to normal Exchange behavior.

There is no documented or supported way to:

• Pass a folder ID in the sendMail request body, or
• Use a header/parameter on sendMail to deliver directly into a specific folder.

For programmatic control of where a message ends up in a mailbox, the supported pattern is:

1. Send or create the message.
2. Move the resulting message into the desired folder using the move operation.

For example, after obtaining the message ID, use Microsoft Graph message move:

POST /users/{id | userPrincipalName}/messages/{id}/move
Content-Type: application/json
Authorization: Bearer {token}

{
  "destinationId": "{target-folder-id-or-well-known-name}"
}

The destinationId can be a folder ID or a supported well-known folder name (see the mailFolder resource type). This API creates a new copy of the message in the destination folder and removes the original.

In PowerShell with the Microsoft Graph Mail module, the equivalent pattern is to call the move cmdlet with a body specifying destinationId, for example:

$params = @{ destinationId = "destination-folder-id" }
Move-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -MessageId $messageId -BodyParameter $params

For large-scale or centralized scenarios, the options are therefore:

• Use sendMail as normal and then move messages via Graph (REST or PowerShell) based on your own routing logic, or
• Use server-side rules (transport/mailbox rules) configured centrally in Exchange Online, not per-user in Outlook, if rule-based routing is acceptable.

There is no API parameter on sendMail itself that bypasses this two-step model.

---

References:

• message: move
• Move-MgUserMailFolderMessage
• Move-MgBetaUserMailFolderMessage
• Move-MgBetaUserMailFolderChildFolderMessage
• mailFolder: move