We’re excited to announce the public preview of the User Configuration API in the Microsoft Graph beta endpoint. The User Configuration API is a new set of endpoints that you can use to create, read, update, and delete user configuration objects in Exchange Online mail folders.  User configuration objects—also known as folder associated items (FAIs)—are items associated with a specific mail folder, and each configuration object in a folder must have a unique key.  

Many solutions need a reliable way to store and retrieve per-folder configuration data alongside mailbox content—whether that’s application state, settings, or other metadata scoped to a folder.  The userConfiguration resource supports multiple payload styles so you can store what best fits your scenario: 

• binaryData: arbitrary binary data 

• xmlData: serialized XML 

• structuredData: key-value pairs of supported data types 

API capabilities

The beta release includes full CRUD support for userConfiguration objects: 

• Create a new userConfiguration 

• Get an existing userConfiguration 

• Update an existing userConfiguration 

• Delete a userConfiguration 

For example, you can read a configuration from either the signed-in user (/me) or a specific user (/users/{id}), scoped to a mail folder: 

• GET /me/mailFolders/{mailFolderId}/userConfigurations/{userConfigurationId}

• GET /users/{usersId}/mailFolders/{mailFolderId}/userConfigurations/{userConfigurationId}

Permissions (least privileged) 

The API uses dedicated permissions for mailbox configuration items: 

• Get supports MailboxConfigItem.Read (least privileged) and MailboxConfigItem.ReadWrite (higher privileged) 

• Create requires MailboxConfigItem.ReadWrite

• Update requires MailboxConfigItem.ReadWrite 

• Delete requires MailboxConfigItem.ReadWrite 

As always, choose the least privileged permissions your application needs. 

Get started 

The easiest way to begin is to explore the API surface and try calls interactively.

Review the resource and method docs: 

• userConfiguration resource type 

• Create userConfiguration

• Get userConfiguration

• Update userConfiguration

• Delete userConfiguration

Use Graph Explorer to test requests quickly: 

• Graph Explorer | Try Microsoft Graph APIs 

We’d love your feedback 

As you explore the User Configuration API in beta, we want to hear what’s working well and where we can improve—especially around usability, gaps, and real-world scenarios. 

Send feedback to: exouserconfigurationapifeedback@microsoft.com