Get user mailbox settings

Namespace: microsoft.graph

Get the user's mailboxSettings. You can view all mailbox settings, or get specific settings.

Users can set the following settings for their mailboxes through an Outlook client:

• automatic replies (notify people automatically upon receipt of their email)
• date format
• delegateMeetingMessageDeliveryOptions
• locale (language and country/region)
• time format
• time zone
• working hours
• user purpose

Users can set their preferred date and time formats using Outlook on the web. Users can choose one of the supported short date or short time formats. This GET operation returns the format the user has chosen.

Users can set the time zone they prefer on any Outlook client, by choosing from the supported time zones that their administrator has set up for their mailbox server. The administrator can set up time zones in the Windows time zone format or Internet Assigned Numbers Authority (IANA) time zone (also known as Olson time zone) format. The Windows format is the default.

This GET operation returns the user's preferred time zone in the format that the administrator has set up. If you want that time zone to be in a specific format (Windows or IANA), you can first update the preferred time zone in that format as a mailbox setting. Subsequently you will be able to get the time zone in that format. Alternatively, you can manage the format conversion separately in your app.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	MailboxSettings.Read	MailboxSettings.ReadWrite
Delegated (personal Microsoft account)	MailboxSettings.Read	MailboxSettings.ReadWrite
Application	MailboxSettings.Read	MailboxSettings.ReadWrite

HTTP request

To get all the mailbox settings for a user:

HTTP

GET /me/mailboxSettings
GET /users/{id|userPrincipalName}/mailboxSettings

To get specific settings - only the automatic replies settings, date format, locale, time format, time zone, working hours, or user's recipient or mailbox type (for example, user purpose):

HTTP

GET /me/mailboxSettings/automaticRepliesSetting
GET /users/{id|userPrincipalName}/mailboxSettings/automaticRepliesSetting

GET /me/mailboxSettings/dateFormat
GET /users/{id|userPrincipalName}/mailboxSettings/dateFormat

GET /me/mailboxSettings/delegateMeetingMessageDeliveryOptions
GET /users/{id|userPrincipalName}/mailboxSettings/delegateMeetingMessageDeliveryOptions

GET /me/mailboxSettings/language
GET /users/{id|userPrincipalName}/mailboxSettings/language

GET /me/mailboxSettings/timeFormat
GET /users/{id|userPrincipalName}/mailboxSettings/timeFormat

GET /me/mailboxSettings/timeZone
GET /users/{id|userPrincipalName}/mailboxSettings/timeZone

GET /me/mailboxSettings/workingHours
GET /users/{id|userPrincipalName}/mailboxSettings/workingHours

GET /me/mailboxSettings/userPurpose
GET /users/{id|userPrincipalName}/mailboxSettings/userPurpose

Optional query parameters

This method supports some of the OData Query Parameters to help customize the response.

Request headers

Name	Type	Description
Authorization	string	Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and one of the following requested objects in the response body:

• mailboxSettings object
• automaticRepliesSetting object
• string (for dateFormat)
• string (for delegateMeetingMessageDeliveryOptions)
• localeInfo object
• string (for timeFormat)
• string (for timeZone)
• workingHours
• userPurpose

Examples

Example 1: Get all mailbox settings of the signed-in user's mailbox

Get all the mailbox settings of the signed-in user's mailbox that include settings for automatic replies, date format, locale (language and country/region), time format, time zone, working hours, and user purpose.

Request

The following example shows a request.

HTTP

msgraph

GET https://graph.microsoft.com/v1.0/me/mailboxSettings

C#

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailboxSettings.GetAsync();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

Bash

mgc users mailbox-settings get --user-id {user-id}

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
mailboxSettings, err := graphClient.Me().MailboxSettings().Get(context.Background(), nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MailboxSettings result = graphClient.me().mailboxSettings().get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let mailboxSettings = await client.api('/me/mailboxSettings')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->mailboxSettings()->get()->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

PowerShell

Import-Module Microsoft.Graph.Users

# A UPN can also be used as -UserId.
Get-MgUserMailboxSetting -UserId $userId

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.me.mailbox_settings.get()

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following is an example of the response that includes all mailbox settings of the signed-in user.

Note: The response object shown here might be shortened for readability.

HTTP

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/mailboxSettings",
    "automaticRepliesSetting": {
        "status": "Scheduled",
        "externalAudience": "All",
        "scheduledStartDateTime": {
            "dateTime": "2016-03-14T07:00:00.0000000",
            "timeZone": "UTC"
        },
        "scheduledEndDateTime": {
            "dateTime": "2016-03-28T07:00:00.0000000",
            "timeZone": "UTC"
        },
        "internalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
        "externalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n"
    },
    "timeZone":"UTC",
    "language":{
      "locale":"en-US",
      "displayName":"English (United States)"
    },
    "workingHours":{
        "daysOfWeek":[
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday"
        ],
        "startTime": "08:00:00.0000000",
        "endTime": "17:00:00.0000000",
        "timeZone":{
            "name":"Pacific Standard Time"
        }
    },
    "userPurpose": {
        "value": "user"
    },
    "dateFormat": "MM/dd/yyyy",
    "timeFormat": "hh:mm tt",
    "delegateMeetingMessageDeliveryOptions": "sendToDelegateOnly"
}

Example 2: Get specifically the automatic replies settings of the signed-in user's mailbox

Request

The following example shows a request.

HTTP

msgraph

GET https://graph.microsoft.com/v1.0/me/mailboxSettings/automaticRepliesSetting

C#

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let automaticRepliesSetting = await client.api('/me/mailboxSettings/automaticRepliesSetting')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following is an example of the response that includes only the automatic replies settings.

Note: The response object shown here might be shortened for readability.

HTTP

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/mailboxSettings/automaticRepliesSetting",
    "status": "alwaysEnabled",
    "externalAudience": "None",
    "scheduledStartDateTime": {
        "dateTime": "2016-03-19T02:00:00.0000000",
        "timeZone": "UTC"
    },
    "scheduledEndDateTime": {
        "dateTime": "2016-03-20T02:00:00.0000000",
        "timeZone": "UTC"
    },
    "internalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
    "externalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n"
}

Example 3: Get specifically the working hour settings of the signed-in user's mailbox

Request

The following example shows a request.

HTTP

msgraph

GET https://graph.microsoft.com/v1.0/me/mailboxSettings/workingHours

C#

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let workingHours = await client.api('/me/mailboxSettings/workingHours')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following is an example of the response that includes only the working hours settings. Notice that the user's work hours are in a custom time zone.

Note: The response object shown here might be shortened for readability.

HTTP

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('94447c6e-ea4c-494c-a9ed-d905e366c5cb')/mailboxSettings/workingHours",
    "daysOfWeek":[
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday",
        "saturday"
    ],
    "startTime":"09:00:00.0000000",
    "endTime":"18:30:00.0000000",
    "timeZone":{
        "@odata.type":"#microsoft.graph.customTimeZone",
        "bias":-200,
        "name":"Customized Time Zone",
        "standardOffset":{
            "time":"02:00:00.0000000",
            "dayOccurrence":4,
            "dayOfWeek":"sunday",
            "month":5,
            "year":0
        },
        "daylightOffset":{
            "daylightBias":-100,
            "time":"02:00:00.0000000",
            "dayOccurrence":2,
            "dayOfWeek":"sunday",
            "month":10,
            "year":0
        }
    }
}

Example 4: Get specifically the user purpose settings of the signed-in user's mailbox

Request

The following example shows a request.

HTTP

msgraph

GET https://graph.microsoft.com/v1.0/me/mailboxSettings/userPurpose

C#

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let userPurpose = await client.api('/me/mailboxSettings/userPurpose')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following is an example of the response that includes only the user purpose settings.

HTTP

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('622eaaff-0683-4862-9de4-f2ec83c2bd98')/mailboxSettings/userPurpose",
    "value": "user"
}