Microsoft Entra ID (formerly Azure AD) Users.mailbox Settings API

The users.mailboxSettings API from Microsoft Entra ID (formerly Azure AD) — 1 operation(s) for users.mailboxsettings.

Documentation GitHub OpenAPI

Operations 2

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /users/{user-id}/mailboxSettings Get a user's mailbox settings · Get mailboxSettings property value #

Ask an LLM

“What are a user's mailbox settings like time zone and language?”

“Can I check whether automatic replies are on for a user?”

Tell an agent

Get mailbox settings for {user}.

Show {user}'s working hours and time zone.

PATCH /users/{user-id}/mailboxSettings Update a user's mailbox settings · Update property mailboxSettings value #

Ask an LLM

“How do I change a user's mailbox time zone?”

“Can I set automatic replies for someone's mailbox?”

Tell an agent

Set the mailbox time zone of {user} to {tz}.

Update automatic replies for {user} to {auto_reply}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/azure-ad:azure-ad-users-mailboxsettings-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Users.mailbox Settings API
  version: v1.0
servers:
- url: https://graph.microsoft.com/v1.0/
  description: Core
security:
- azureaadv2: []
tags:
- name: users.mailboxSettings
paths:
  /users/{user-id}/mailboxSettings:
    get:
      tags:
      - users.mailboxSettings
      summary: Get mailboxSettings property value
      description: Settings for the primary mailbox of the signed-in user. You can get or update settings for sending automatic replies to incoming messages, locale, and time zone. Requires $select to retrieve.
      operationId: user_GetMailboxSetting
      parameters:
      - name: user-id
        in: path
        description: The unique identifier of user
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: user
      - name: $select
        in: query
        description: Select properties to be returned
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: $expand
        in: query
        description: Expand related entities
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        2XX:
          description: Entity result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.mailboxSettings'
        default:
          $ref: '#/components/responses/error'
    patch:
      tags:
      - users.mailboxSettings
      summary: Update property mailboxSettings value
      operationId: user_UpdateMailboxSetting
      parameters:
      - name: user-id
        in: path
        description: The unique identifier of user
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: user
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/microsoft.graph.mailboxSettings'
        required: true
      responses:
        2XX:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.mailboxSettings'
        default:
          $ref: '#/components/responses/error'
components:
  responses:
    error:
      description: error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError'
  schemas:
    microsoft.graph.mailboxSettings:
      title: mailboxSettings
      type: object
      properties:
        archiveFolder:
          type:
          - string
          - 'null'
          description: Folder ID of an archive folder for the user.
        automaticRepliesSetting:
          $ref: '#/components/schemas/microsoft.graph.automaticRepliesSetting'
        dateFormat:
          type:
          - string
          - 'null'
          description: The date format for the user's mailbox.
        delegateMeetingMessageDeliveryOptions:
          $ref: '#/components/schemas/microsoft.graph.delegateMeetingMessageDeliveryOptions'
        language:
          $ref: '#/components/schemas/microsoft.graph.localeInfo'
        timeFormat:
          type:
          - string
          - 'null'
          description: The time format for the user's mailbox.
        timeZone:
          type:
          - string
          - 'null'
          description: The default time zone for the user's mailbox.
        userPurpose:
          $ref: '#/components/schemas/microsoft.graph.userPurpose'
        workingHours:
          $ref: '#/components/schemas/microsoft.graph.workingHours'
      additionalProperties:
        type: object
    microsoft.graph.dateTimeTimeZone:
      title: dateTimeTimeZone
      type: object
      properties:
        dateTime:
          type: string
          description: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000).
        timeZone:
          type:
          - string
          - 'null'
          description: Represents a time zone, for example, 'Pacific Standard Time'. See below for more possible values.
      additionalProperties:
        type: object
    microsoft.graph.externalAudienceScope:
      title: externalAudienceScope
      enum:
      - none
      - contactsOnly
      - all
      type: string
    microsoft.graph.userPurpose:
      title: userPurpose
      enum:
      - user
      - linked
      - shared
      - room
      - equipment
      - others
      - unknownFutureValue
      type: string
    microsoft.graph.workingHours:
      title: workingHours
      type: object
      properties:
        daysOfWeek:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.dayOfWeek'
          description: The days of the week on which the user works.
        endTime:
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?$
          type:
          - string
          - 'null'
          description: The time of the day that the user stops working.
          format: time
        startTime:
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?$
          type:
          - string
          - 'null'
          description: The time of the day that the user starts working.
          format: time
        timeZone:
          $ref: '#/components/schemas/microsoft.graph.timeZoneBase'
      additionalProperties:
        type: object
    microsoft.graph.ODataErrors.InnerError:
      type: object
      additionalProperties:
        type: object
      description: The structure of this object is service-specific
    microsoft.graph.ODataErrors.ODataError:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.MainError'
      additionalProperties:
        type: object
    microsoft.graph.ODataErrors.MainError:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
          x-ms-primary-error-message: true
        target:
          type:
          - string
          - 'null'
        details:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ErrorDetails'
        innerError:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.InnerError'
      additionalProperties:
        type: object
    microsoft.graph.dayOfWeek:
      title: dayOfWeek
      enum:
      - sunday
      - monday
      - tuesday
      - wednesday
      - thursday
      - friday
      - saturday
      type: string
    microsoft.graph.timeZoneBase:
      title: timeZoneBase
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: The name of a time zone. It can be a standard time zone name such as 'Hawaii-Aleutian Standard Time', or 'Customized Time Zone' for a custom time zone.
      additionalProperties:
        type: object
    microsoft.graph.localeInfo:
      title: localeInfo
      type: object
      properties:
        displayName:
          type:
          - string
          - 'null'
          description: A name representing the user's locale in natural language, for example, 'English (United States)'.
        locale:
          type:
          - string
          - 'null'
          description: A locale representation for the user, which includes the user's preferred language and country/region. For example, 'en-us'. The language component follows 2-letter codes as defined in ISO 639-1, and the country component follows 2-letter codes as defined in ISO 3166-1 alpha-2.
      additionalProperties:
        type: object
    microsoft.graph.automaticRepliesStatus:
      title: automaticRepliesStatus
      enum:
      - disabled
      - alwaysEnabled
      - scheduled
      type: string
    microsoft.graph.automaticRepliesSetting:
      title: automaticRepliesSetting
      type: object
      properties:
        externalAudience:
          $ref: '#/components/schemas/microsoft.graph.externalAudienceScope'
        externalReplyMessage:
          type:
          - string
          - 'null'
          description: The automatic reply to send to the specified external audience, if Status is AlwaysEnabled or Scheduled.
        internalReplyMessage:
          type:
          - string
          - 'null'
          description: The automatic reply to send to the audience internal to the signed-in user's organization, if Status is AlwaysEnabled or Scheduled.
        scheduledEndDateTime:
          $ref: '#/components/schemas/microsoft.graph.dateTimeTimeZone'
        scheduledStartDateTime:
          $ref: '#/components/schemas/microsoft.graph.dateTimeTimeZone'
        status:
          $ref: '#/components/schemas/microsoft.graph.automaticRepliesStatus'
      additionalProperties:
        type: object
    microsoft.graph.delegateMeetingMessageDeliveryOptions:
      title: delegateMeetingMessageDeliveryOptions
      enum:
      - sendToDelegateAndInformationToPrincipal
      - sendToDelegateAndPrincipal
      - sendToDelegateOnly
      type: string
    microsoft.graph.ODataErrors.ErrorDetails:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type:
          - string
          - 'null'
      additionalProperties:
        type: object
  securitySchemes:
    azureaadv2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes: {}