Share via

Mailbox endpoint in the Exchange Online Admin API

Note

The features described in this article are currently in Preview, aren't available in all organizations, and are subject to change.

The Mailbox endpoint in the Exchange Online Admin API lets you view and manage Send on behalf delegates.

Typical use cases include:

  • List mailboxes or retrieve details for a specific mailbox.
  • Inspect delegate configuration for SendOnBehalfTo, including optional display names for delegates.
  • Update Send on behalf delegates by overwriting the full delegate list or making incremental changes (add/remove).

The Exchange Online Admin API provides a REST-based way to execute specific PowerShell cmdlets, replacing legacy Exchange Web Services (EWS) scenarios. For more information, see Overview of the Exchange Online Admin API.

Endpoint URL

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox

Tip

Use the base URL for your environment as described in Supported environments and base URLs.

Request model

Headers

Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <routing hint>

For X-AnchorMailbox values, see X-AnchorMailbox routing hint.

Body

  • Get-Mailbox:

    {
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                        //optional
      "ResultSize": <Integer | "Unlimited">,                 //optional (pagination)
      "IncludeGrantSendOnBehalfTowithDisplayNames": true     //optional
    }
  }
}

  • Set-Mailbox (overwrite delegates):

    {
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",      //required
      "GrantSendOnBehalfTo": [             //required
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

  • Set-Mailbox (add/remove delegates):

    {
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                //required
      "GrantSendOnBehalfTo": {                       //required
        "add": ["delegate3@contoso.com"],
        "remove": ["delegate1@contoso.com"],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}

Pagination

The ResultSize parameter on the Get-Mailbox cmdlet controls pagination. By default, up to 1,000 results are returned.

If more results are available, the response includes an @odata.nextLink property with a continuation URL. To fetch the next page, issue a new POST request to the URL in @odata.nextLink with the same body.

Property selection

This endpoint supports the $select query parameter to return only specific properties in the response.

Supported cmdlets and parameters

The following list describes the cmdlets and parameters supported by this endpoint. Other cmdlets in the body of this endpoint result in an error.

  • Get-Mailbox:

    Only the parameters for Get-Mailbox described in the following table are available through the REST endpoint:

    Parameter Required Type Description
    Identity Optional String Specifies the mailbox to retrieve information about. Valid values are name, distinguished name, alias, user principal name (UPN), GUID, or other unique identifier. If omitted and subject to ResultSize, the cmdlet returns all mailboxes.
    ResultSize Optional Integer or Unlimited Limits the number of results returned. Valid values are an integer (for example, 10) or the value "Unlimited".
    IncludeGrantSendOnBehalfToWithDisplayNames Optional Boolean The value True includes SendOnBehalfTo delegate entries with their display names.

    NOTE: This parameter is in staged rollout and might not be available in all organizations.

  • Set-Mailbox:

    Only the parameters for Set-Mailbox described in the following table are available through the REST endpoint:

    Parameter Required Type Description
    Identity Optional String Specifies the target mailbox. Valid values are name, distinguished name, alias, UPN, GUID, or other unique identifier.
    GrantSendOnBehalfTo Required Collection or hash table
    • Overwrite: List of SMTP address for the complete delegate list. For example, ["bob@contoso.com","carol@contoso.com"].
    • Add/remove: Hash table with add and/or remove arrays to modify the delegate list. For example, { "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }.

Response overview

Note

During Preview, the endpoint includes the full Get-Mailbox cmdlet output in the API response. During the transition to public release, the response will be limited to the core properties listed in this section (properties needed for the EWS‑equivalent scenario). We recommend you use the properties listed in this section only. We'll document any changes to the available properties.

  • The Get-Mailbox response is a JSON object or a list array with mailbox properties. The following properties are returned:

    • Identity: Canonical identifier for the mailbox (often the alias or distinguished name).
    • Id: Service identifier for the mailbox object.
    • Name: Unique Exchange display name for the mailbox.
    • DisplayName: User-friendly display name.
    • UserPrincipalName: Account associated with the mailbox.
    • Alias: Unique mailbox alias.
    • ExternalDirectoryObjectId: Microsoft Entra ID object GUID for the mailbox.
    • RecipientType: For possible mailbox values, see RecipientType.
    • RecipientTypeDetails: For possible mailbox values, see RecipientTypeDetails.
    • EmailAddresses: All proxy addresses for the recipient (including SMTP: and smtp: entries).
    • PrimarySmtpAddress: Primary SMTP address for the recipient (corresponds to the SMTP: value in EmailAddresses).
    • MaxSendSize: Maximum message size the mailbox can send.
    • GrantSendOnBehalfTo: List of delegates (SMTP addresses) granted Send on behalf permissions for the mailbox.
    • GrantSendOnBehalfToWithDisplayNames: Same list with delegate display names (when requested).

  • The Set-Mailbox cmdlet returns HTTP 200 OK on success. No response body is required for successful updates.

Examples

  • Example 1: Simple Get-Mailbox (paged listing):

    This example lists the first 10 mailboxes in the organization. Use @odata.nextLink to continue.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "ResultSize": 10
    }
  }
}

  • Example 2: Get-Mailbox for a specific mailbox and include delegate display names:

    This example returns mailbox details and SendOnBehalfTo delegates with display names.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "IncludeGrantSendOnBehalfTowithDisplayNames": true
    }
  }
}

  • Example 3: Set-Mailbox: Overwrite the delegate list:

    This example overwrites the SendOnBehalfTo list on the specified mailbox with the specified delegates.

    The result is: 200 OK. delegate1@contoso.com and delegate2@contoso.com replace any/all existing SendOnBehalfTo delegates on the mailbox.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo@odata.type": "#Collection(String)",
      "GrantSendOnBehalfTo": [
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

  • Example 4: Set-Mailbox: Add delegates to the existing delegate list:

    This example adds new SendOnBehalfTo delegates to the specified mailbox while preserving the existing delegates.

    The result is: 200 OK. delegate3@contoso.com and delegate4@contoso.com are added to the existing list of delegates on the mailbox.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo": {
        "add": [
          "delegate3@contoso.com",
          "delegate4@contoso.com"
        ],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}
  • Last updated on