Action required: Exchange Online Admin API MailboxFolderPermission response update

[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.