获取用户的邮箱设置

  • 项目

命名空间：microsoft.graph

在用户的 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 如果用户具有日历代理人，这将指定是代理人、邮箱所有者还是同时接收会议消息和会议响应。 可取值为：sendToDelegateAndInformationToPrincipal、sendToDelegateAndPrincipal、sendToDelegateOnly。
language localeInfo 用户的区域设置信息，包括首选语言和国家/地区。
timeFormat string 用户邮箱的时间格式。
timeZone string 用户邮箱的默认时区。
workingHours workingHours 用户工作的小时数、一周的天数和时区。

响应

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

错误

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

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

示例

示例 1

请求

第一个示例通过设置 automaticRepliesSetting 属性的以下属性来启用对日期范围的自动答复：status、scheduledStartDateTime 和 scheduledEndDateTime。

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

响应

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

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-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/v1.0/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/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
            }
        }
    }
}