| title | description | ms.localizationpriority | author | ms.subservice | doc_type | ms.date |
|---|---|---|---|---|---|---|
Update user mailbox settings | Update one or more settings for the user's mailbox. This includes settings for automatic replies (notify people automatically upon receipt of their email), locale (language and country/region), time zone, and working hours. | medium | SuryaLashmiS | outlook | apiPageType | 06/21/2024 |
Namespace: microsoft.graph
Enable, configure, or disable one or more of the following settings as part of a user's mailboxSettings:
- automatic replies (notify people automatically upon receipt of their email)
- dateFormat
- delegateMeetingMessageDeliveryOptions
- locale (language and country/region)
- timeFormat
- time zone
- working hours
When updating the preferred date or time format for a user, specify it in respectively, the short date or short time format.
When updating the preferred time zone for a user, specify it in the Windows or Internet Assigned Numbers Authority (IANA) time zone (also known as Olson time zone) format. You can also further customize the time zone as shown in example 2 below.
Tip
You cannot create or delete any mailbox settings.
[!INCLUDE national-cloud-support]
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.
[!INCLUDE permissions-table]
PATCH /me/mailboxSettingsPATCH /users/{id|userPrincipalName}/mailboxSettingsThis method supports the OData Query Parameters to help customize the response.
| Name | Type | Description |
|---|---|---|
| Authorization | string | Bearer {token}. Required. Learn more about authentication and authorization. |
In the request body, supply the values for the relevant properties that should be updated. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't changed. The following are the writable/updatable properties:
| Property | Type | Description |
|---|---|---|
| automaticRepliesSetting | automaticRepliesSetting | Configuration settings to automatically notify the sender of an incoming email with a message from the signed-in user. You can set such notifications for only a future date range. |
| dateFormat | string | The date format for the user's mailbox. |
| delegateMeetingMessageDeliveryOptions | delegateMeetingMessageDeliveryOptions | If the user has a calendar delegate, this specifies whether the delegate, mailbox owner, or both receive meeting messages and meeting responses. Possible values are: sendToDelegateAndInformationToPrincipal, sendToDelegateAndPrincipal, sendToDelegateOnly. |
| language | localeInfo | The locale information for the user, including the preferred language and country/region. |
| timeFormat | string | The time format for the user's mailbox. |
| timeZone | string | The default time zone for the user's mailbox. |
| workingHours | workingHours | The hours, days of a week, and time zone that the user works. |
If successful, this method returns a 200 OK response code and the updated properties of a mailboxSettings object in the response body.
Setting working hours with inappropriate values may return the following errors.
| Scenario | HTTP status code | Error code | Error message |
|---|---|---|---|
| Invalid startTime or endTime | 400 | RequestBodyRead | Cannot convert the literal '08' to the expected type 'Edm.TimeOfDay'. |
| Start time is greater than end time | 400 | ErrorInvalidTimeSettings | Start Time should occur before End Time. |
| Invalid day in daysOfWeek | 400 | InvalidArguments | Requested value 'RandomDay' was not found. |
| Invalid timeZone | 400 | InvalidTimeZone | Time Zone settings provided are invalid. |
The first example enables automatic replies for a date range, by setting the following properties of the automaticRepliesSetting property: status, scheduledStartDateTime and scheduledEndDateTime.
PATCH https://graph.microsoft.com/v1.0/me/mailboxSettingsContent-Type: application/json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/mailboxSettings", "automaticRepliesSetting": { "status": "Scheduled", "scheduledStartDateTime": { "dateTime": "2016-03-20T18:00:00.0000000", "timeZone": "UTC" }, "scheduledEndDateTime": { "dateTime": "2016-03-28T18:00:00.0000000", "timeZone": "UTC" } } }[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The response includes the updated settings for automatic replies. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OKContent-type: application/json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/mailboxSettings", "automaticRepliesSetting": { "status": "scheduled", "externalAudience": "all", "scheduledStartDateTime": { "dateTime": "2016-03-20T02:00:00.0000000", "timeZone": "UTC" }, "scheduledEndDateTime": { "dateTime": "2016-03-28T02: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" } }The second example customizes the time zone for the working hours of the signed-in user, by setting the timeZone property to a custom time zone.
PATCH https://graph.microsoft.com/v1.0/me/mailboxSettingsContent-Type: application/json { "workingHours": { "endTime" : "18:30:00.0000000", "daysOfWeek": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ], "timeZone" : { "@odata.type": "#microsoft.graph.customTimeZone", "bias":-300, "name": "Customized Time Zone", "standardOffset":{ "time":"02:00:00.0000000", "dayOccurrence":2, "dayOfWeek":"Sunday", "month":10, "year":0 }, "daylightOffset":{ "daylightBias":100, "time":"02:00:00.0000000", "dayOccurrence":4, "dayOfWeek":"Sunday", "month":5, "year":0 } } }} [!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OKContent-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 } } } }