获取用户的邮箱设置

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

在用户的 mailboxSettings 中启用、配置或禁用以下一个或多个设置:

  • 自动答复(收到发件人的电子邮件时自动通知发件人)
  • dateFormat
  • delegateMeetingMessageDeliveryOptions
  • 区域设置(语言和国家/地区)
  • timeFormat
  • 时区
  • 工作时间

更新用户的首选日期或时间格式时,请分别以 短日期短时间 格式指定它。

更新用户的首选时区时,请在 Windows 或 Internet 号码分配机构 (IANA) 时区 (也称为 Olson 时区) 格式指定它。 还可以进一步自定义时区,如以下示例 2 所示。

提示

无法创建或删除任何邮箱设置。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) MailboxSettings.ReadWrite 不可用。
委派(个人 Microsoft 帐户) MailboxSettings.ReadWrite 不可用。
应用程序 MailboxSettings.ReadWrite 不可用。

HTTP 请求

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

可选的查询参数

此方法支持 OData 查询参数 来帮助自定义响应。

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权

请求正文

在请求正文中,提供应更新的相关属性的值。 请求正文中不包括的现有属性将保留其以前的值,或根据对其他属性值的更改重新计算。 为了获得最佳性能,不应包括尚未更改的现有值。 以下是可写/可更新的属性:

属性 类型 说明
automaticRepliesSetting automaticRepliesSetting 自动通知发件人有传入电子邮件(包含一封来自已登录用户的邮件)的配置设置。 只能为将来的日期范围设置此类通知。
dateFormat string 用户邮箱的日期格式。
delegateMeetingMessageDeliveryOptions delegateMeetingMessageDeliveryOptions 如果用户具有日历代理人,这将指定是代理人、邮箱所有者还是同时接收会议消息和会议响应。 可取值为:sendToDelegateAndInformationToPrincipalsendToDelegateAndPrincipalsendToDelegateOnly
language localeInfo 用户的区域设置信息,包括首选语言和国家/地区。
timeFormat string 用户邮箱的时间格式。
timeZone string 用户邮箱的默认时区。
workingHours workingHours 用户工作的小时数、一周的天数和时区。

响应

如果成功,此方法在 200 OK 响应正文中返回响应代码和 mailboxSettings 对象的更新属性。

错误

将工作时间设置为不适当的值可能会返回以下错误。

应用场景 HTTP 状态代码 错误代码 错误消息
startTimeendTime 无效 400 RequestBodyRead 无法将文本“08”转换为预期类型“Edm.TimeOfDay”。
开始时间大于结束时间 400 ErrorInvalidTimeSettings 开始时间应早于结束时间。
daysOfWeek 中的天数无效 400 InvalidArguments 未找到请求值“RandomDay”。
timeZone 无效 400 InvalidTimeZone 提供的时区设置无效。

示例

示例 1

请求

第一个示例通过设置 automaticRepliesSetting 属性的以下属性来启用对日期范围的自动答复:statusscheduledStartDateTimescheduledEndDateTime

PATCH https://graph.microsoft.com/beta/me/mailboxSettings
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$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"
        }
    }
}

响应

该响应包括自动答复的更新设置。 注意:为了提高可读性,可能缩短了此处显示的响应对象。

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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"
    }
}

示例 2

请求

第二个示例通过将 timeZone 属性设置为自定义时区,为登录用户的工作时间自定义时区。

PATCH https://graph.microsoft.com/beta/me/mailboxSettings
Content-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 
         } 
      } 
  }
} 

响应

以下示例显示了相应的响应。 注意:为了提高可读性,可能缩短了此处显示的响应对象。

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

{
    "@odata.context":"https://graph.microsoft.com/beta/$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
            }
        }
    }
}