{"id":25248,"date":"2026-01-28T10:59:42","date_gmt":"2026-01-28T18:59:42","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/?p=25248"},"modified":"2026-01-28T10:59:42","modified_gmt":"2026-01-28T18:59:42","slug":"introducing-the-microsoft-graph-user-configuration-api-preview","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/introducing-the-microsoft-graph-user-configuration-api-preview\/","title":{"rendered":"Introducing the Microsoft Graph User Configuration API (preview)"},"content":{"rendered":"<p><span data-contrast=\"auto\">We\u2019re 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.\u00a0\u00a0User configuration objects\u2014also known as folder associated items (FAIs)\u2014are items associated with a specific mail folder, and each configuration object in a folder must have a unique key. <\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<p><span data-contrast=\"auto\">Many solutions need a reliable way to store and retrieve per-folder configuration data alongside mailbox content\u2014whether that\u2019s application state, settings, or other metadata scoped to a folder.\u00a0\u00a0The\u00a0<strong>userConfiguration<\/strong>\u00a0resource\u00a0supports multiple payload styles so you can store what best fits your scenario:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"2\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"1\" data-aria-level=\"1\"><span data-contrast=\"auto\"><strong>binaryData<\/strong>: arbitrary binary data<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"2\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"2\" data-aria-level=\"1\"><span data-contrast=\"auto\"><strong>xmlData<\/strong>:\u00a0serialized XML<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"2\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"3\" data-aria-level=\"1\"><span data-contrast=\"auto\"><strong>structuredData<\/strong>: key-value pairs of supported data types<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<h2>API capabilities<\/h2>\n<p><span data-contrast=\"auto\">The beta release includes full CRUD support for\u00a0<strong>userConfiguration<\/strong>\u00a0objects:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"4\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"1\" data-aria-level=\"1\">Create<span data-contrast=\"auto\">\u00a0a new\u00a0<strong>userConfiguration<\/strong><\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"4\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"2\" data-aria-level=\"1\">Get<span data-contrast=\"auto\">\u00a0an existing\u00a0<strong>userConfiguration<\/strong><\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"4\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"3\" data-aria-level=\"1\">Update<span data-contrast=\"auto\">\u00a0an existing\u00a0<strong>userConfiguration<\/strong><\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"4\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"4\" data-aria-level=\"1\">Delete<span data-contrast=\"auto\">\u00a0a\u00a0<strong>userConfiguration<\/strong><\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<p><span data-contrast=\"auto\">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:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li class=\"prettyprint language-html\"><code class=\"language-html\">GET \/me\/mailFolders\/{mailFolderId}\/userConfigurations\/{userConfigurationId}<\/code><\/li>\n<\/ul>\n<ul>\n<li class=\"prettyprint language-html\"><code class=\"language-html\">GET\u00a0\/users\/{usersId}\/mailFolders\/{mailFolderId}\/userConfigurations\/{userConfigurationId}<\/code><\/li>\n<\/ul>\n<h2><b><span data-contrast=\"auto\">Permissions (least privileged)<\/span><\/b><span data-ccp-props=\"{}\">\u00a0<\/span><\/h2>\n<p><span data-contrast=\"auto\">The API uses dedicated permissions for mailbox configuration items:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"6\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"1\" data-aria-level=\"1\">Get<span data-contrast=\"auto\">\u00a0supports\u00a0<code>MailboxConfigItem.Read<\/code>\u00a0(least privileged) and\u00a0<code>MailboxConfigItem.ReadWrite<\/code>\u00a0(higher privileged)<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"6\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"2\" data-aria-level=\"1\">Create<span data-contrast=\"auto\">\u00a0requires\u00a0<code>MailboxConfigItem.ReadWrite<\/code><\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"6\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"3\" data-aria-level=\"1\">Update<span data-contrast=\"auto\">\u00a0requires\u00a0<code>MailboxConfigItem.ReadWrite<\/code><\/span><code><span data-ccp-props=\"{}\">\u00a0<\/span><\/code><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"6\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"4\" data-aria-level=\"1\">Delete <span data-contrast=\"auto\">requires\u00a0<code>MailboxConfigItem.ReadWrite<\/code><\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<p><span data-contrast=\"auto\">As always, choose the\u00a0<\/span><b><span data-contrast=\"auto\">l<\/span><\/b>east privileged permissions<span data-contrast=\"auto\">\u00a0your application needs.<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<h2><b><span data-contrast=\"auto\">Get started<\/span><\/b><span data-ccp-props=\"{}\">\u00a0<\/span><\/h2>\n<p><span data-contrast=\"auto\">The easiest way to begin is to explore the API surface and try calls interactively.<\/span><\/p>\n<p><span data-contrast=\"auto\">Review the resource and method docs:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"o\" data-font=\"Courier New\" data-listid=\"7\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:1440,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Courier New&quot;,&quot;469769242&quot;:[9675],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;o&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"1\" data-aria-level=\"2\"><a href=\"https:\/\/learn.microsoft.com\/en-us\/graph\/api\/resources\/userconfiguration?view=graph-rest-beta\"><span data-contrast=\"none\">userConfiguration resource type<\/span><\/a><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"o\" data-font=\"Courier New\" data-listid=\"7\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:1440,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Courier New&quot;,&quot;469769242&quot;:[9675],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;o&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"2\" data-aria-level=\"2\"><a href=\"https:\/\/learn.microsoft.com\/en-us\/graph\/api\/mailsearchfolder-post-userconfigurations?view=graph-rest-beta\"><span data-contrast=\"none\">Create userConfiguration<\/span><\/a><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"o\" data-font=\"Courier New\" data-listid=\"7\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:1440,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Courier New&quot;,&quot;469769242&quot;:[9675],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;o&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"3\" data-aria-level=\"2\"><a href=\"https:\/\/learn.microsoft.com\/en-us\/graph\/api\/userconfiguration-get?view=graph-rest-beta\"><span data-contrast=\"none\">Get userConfiguration<\/span><\/a><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"o\" data-font=\"Courier New\" data-listid=\"7\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:1440,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Courier New&quot;,&quot;469769242&quot;:[9675],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;o&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"4\" data-aria-level=\"2\"><a href=\"https:\/\/learn.microsoft.com\/en-us\/graph\/api\/userconfiguration-update?view=graph-rest-beta\"><span data-contrast=\"none\">Update userConfiguration<\/span><\/a><\/li>\n<\/ul>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"o\" data-font=\"Courier New\" data-listid=\"7\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:1440,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Courier New&quot;,&quot;469769242&quot;:[9675],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;o&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"5\" data-aria-level=\"2\"><a href=\"https:\/\/learn.microsoft.com\/en-us\/graph\/api\/userconfiguration-delete?view=graph-rest-beta\"><span data-contrast=\"none\">Delete userConfiguration<\/span><\/a><\/li>\n<\/ul>\n<p><span data-contrast=\"auto\">Use Graph Explorer to test requests quickly:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li aria-setsize=\"-1\" data-leveltext=\"o\" data-font=\"Courier New\" data-listid=\"7\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559685&quot;:1440,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Courier New&quot;,&quot;469769242&quot;:[9675],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;o&quot;,&quot;469777815&quot;:&quot;multilevel&quot;}\" data-aria-posinset=\"1\" data-aria-level=\"2\"><a href=\"https:\/\/developer.microsoft.com\/en-us\/graph\/graph-explorer\"><span data-contrast=\"none\">Graph Explorer | Try Microsoft Graph APIs<\/span><\/a><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<h2><b><span data-contrast=\"auto\">We\u2019d\u00a0love your feedback<\/span><\/b><span data-ccp-props=\"{}\">\u00a0<\/span><\/h2>\n<p><span data-contrast=\"auto\">As you explore the\u00a0User Configuration API\u00a0in beta, we want to hear\u00a0what\u2019s\u00a0working well and where we can improve\u2014especially around usability, gaps, and real-world scenarios.<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<p><span data-contrast=\"auto\">Send feedback to:\u00a0<\/span><a href=\"mailto:exouserconfigurationapifeedback@microsoft.com\"><span data-contrast=\"none\">exouserconfigurationapifeedback@microsoft.com<\/span><\/a><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The User Configuration API is now available in the beta endpoint in Microsoft Graph.  Use it to create, read, update, and delete user configuration objects in Exchange Online mail folders.<\/p>\n","protected":false},"author":135171,"featured_media":25159,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[],"class_list":["post-25248","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph"],"acf":[],"blog_post_summary":"<p>The User Configuration API is now available in the beta endpoint in Microsoft Graph.  Use it to create, read, update, and delete user configuration objects in Exchange Online mail folders.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/25248","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/135171"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=25248"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/25248\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=25248"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=25248"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=25248"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}