MC1540342 - Action required: Exchange Online Admin API MailboxFolderPermission response update
Microsoft 365 Message Center announcement MC1540342.
MS Message Center's Summary
Microsoft is updating the Exchange Online Admin API MailboxFolderPermission endpoint in early November 2026 to return the User property as a structured object containing DisplayName, Name, and PrimarySmtpAddress instead of a string. Administrators must review custom applications and third party tools that consume this endpoint to update their parsing logic and prevent failures before the rollout completes in January 2027.
- Administrator impact
- Custom applications and integrations consuming the MailboxFolderPermission endpoint must be updated to handle the new structured User property.
- End user impact
- End users might experience failures in custom tools or third party solutions that manage mailbox folder permissions if code updates are not completed.
- Importance
- 6/10: This change alters an API response structure and requires proactive code updates to prevent application errors.
Microsoft Summary
Microsoft will update the Exchange Online Admin API v2.0 MailboxFolderPermission endpoint to return the User property as a structured object with DisplayName, Name, and PrimarySmtpAddress by early November 2026. Organizations must update applications to handle this change to avoid errors.
- Message Center ID
- MC1540342
- Category
- plan For Change
- Severity
- normal
- Services
- Exchange Online
- Tags
- Admin impact
- Published
- 2026-11-05
- Last updated
- 2026-11-05
- Expires
- 2027-01-25
[What and why:] 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.