Summary
- Exchange Online Admin API v2.0 MailboxFolderPermission will change the `User` field from a display-name string to a structured object.
- The new `User` object will include `DisplayName`, `Name`, and `PrimarySmtpAddress`, improving reliability when identifying users with similar names.
- Organizations with applications or third-party tools that parse the current string response may see parsing failures or unexpected behavior after the update.
- Update any code, integrations, or vendor solutions that read this endpoint to handle the new object format and use `PrimarySmtpAddress` where appropriate.
Primary Service: Exchange
Admin Impact: Medium
User Impact: Low
Release Start: 06 Nov 2026
Release End: 06 Nov 2026
Services: Exchange
Category: Plan for change
Tags: Admin Action
History
11/5/2026 Item Added to Message Center
Microsoft Message
Microsoft is updating the Exchange Online Admin API v2.0 MailboxFolderPermission endpoint to return the User property as a structured object instead of a display-name string. The new response includes DisplayName, Name, and PrimarySmtpAddress, helping applications more reliably identify users with similar or identical display names and supporting mailbox folder permission management and EWS migration scenarios.
Rollout schedule
Rollout will begin and is expected to complete in early November 2026.
Impact on your organization
Who is affected
Organizations with applications or third-party solutions that use the Exchange Online Admin API v2.0 MailboxFolderPermission endpoint and process the User property.
Platforms/Services
Exchange Online Admin API v2.0, specifically the MailboxFolderPermission endpoint.
What will happen
- The User property will change from a string to a structured object.
- The object will contain DisplayName, Name, and PrimarySmtpAddress.
- The endpoint URL and API version will not change.
- Applications that expect User to be a string may experience parsing errors or unexpected behavior after the change.
- Applications can use PrimarySmtpAddress to more reliably distinguish between users with similar display names.
Current response:
{
"User": "<display name>"
}
New response:
{
"User": {
"DisplayName": "...",
"Name": "...",
"PrimarySmtpAddress": "..."
}
}
Action required/recommendations
- Action is required if your organization uses the MailboxFolderPermission endpoint and processes the User property. Before rollout:
- Review applications that read or process the User property.
- Update response handling to process User as a structured object instead of a string.
- Where appropriate, use PrimarySmtpAddress to identify the user associated with a mailbox folder permission.
- Test permission retrieval, user identification, and mailbox folder permission management workflows.
- Update dependent integrations that store, consume, or forward the User property.
- If you use a third-party solution that manages mailbox folder permissions, contact the solution provider to determine whether an update is required.
- For more information, see Exchange Online Admin API overview.
Compliance considerations
No compliance considerations identified, review as appropriate for your organization.