Exchange Online 管理 API のメールボックスエンドポイント

注:

この記事で説明されている機能は現在プレビュー段階であり、すべての組織で利用できるわけではありません。変更される可能性があります。

Exchange Online 管理 API のメールボックスエンドポイントを使用すると、代理人に代わって送信を表示および管理できます。

一般的なユースケースは次のとおりです。

メールボックスを一覧表示するか、特定のメールボックスの詳細を取得します。
デリゲートのオプションの表示名など、SendOnBehalfTo のデリゲート構成を調べます。
代理人の完全な一覧を上書きするか、増分変更 (追加/削除) を行って、代理人に代わって送信を更新します。

Exchange Online 管理 API は、従来の Exchange Web Services (EWS) シナリオを置き換えて、特定の PowerShell コマンドレットを実行するための REST ベースの方法を提供します。詳細については、「Exchange Online 管理 API の概要」を参照してください。

エンドポイント URL

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

ヒント

「サポートされている環境と基本 URL」の説明に従って、環境のベース URL を使用します。

要求モデル

ヘッダー

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

X-AnchorMailbox の値については、「X-AnchorMailbox ルーティングヒント」を参照してください。

Body

Get-Mailbox:

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

Set-Mailbox (上書きデリゲート):

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

Set-Mailbox (デリゲートの追加/削除):

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

改ページ

Get-Mailbox コマンドレットの ResultSize パラメーターは、改ページを制御します。既定では、最大 1,000 件の結果が返されます。

より多くの結果が使用可能な場合、応答には継続 URL を持つ @odata.nextLink プロパティが含まれます。次のページをフェッチするには、同じ本文で @odata.nextLink の URL に新しい POST 要求を発行します。

プロパティの選択

このエンドポイントは、応答内の特定のプロパティのみを返すために、 $select クエリパラメーターをサポートします。

サポートされているコマンドレットとパラメーター

次の一覧では、このエンドポイントでサポートされるコマンドレットとパラメーターについて説明します。このエンドポイントの本文内の他のコマンドレットでは、エラーが発生します。

Get-Mailbox:

REST エンドポイントを使用して使用できるのは、次の表で説明する Get-Mailbox のパラメーターのみです。

パラメーター	必須	型	説明
Identity	省略可能	文字列	情報を取得するメールボックスを指定します。有効な値は、名前、識別名、別名、ユーザープリンシパル名 (UPN)、GUID、またはその他の一意識別子です。省略され、 ResultSize の対象となる場合、コマンドレットはすべてのメールボックスを返します。
ResultSize	省略可能	整数または無制限	返される結果の数を制限します。有効な値は、整数 (10 など) または `"Unlimited"`値です。
IncludeGrantSendOnBehalfToWithDisplayNames	省略可能	ブール型	`True`値には、SendOnBehalfTo デリゲートエントリとその表示名が含まれます。注: このパラメーターは段階的なロールアウトにあり、一部の組織では使用できない場合があります。

Set-Mailbox:

REST エンドポイントでは、次の表で説明する Set-Mailbox のパラメーターのみを使用できます。

パラメーター	必須	型	説明
Identity	省略可能	文字列	ターゲットメールボックスを指定します。有効な値は、名前、識別名、別名、UPN、GUID、またはその他の一意の識別子です。
GrantSendOnBehalfTo	必須	コレクションまたはハッシュテーブル	上書き: 完全なデリゲートリストの SMTP アドレスの一覧。たとえば、「 `["bob@contoso.com","carol@contoso.com"]` 」のように入力します。追加/削除: `add` 配列または `remove` 配列を含むハッシュテーブルを使用して、デリゲートリストを変更します。たとえば、「 `{ "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }` 」のように入力します。

応答の概要

注:

プレビュー中、エンドポイントには、API 応答に Get-Mailbox コマンドレットの完全な出力が含まれます。パブリックリリースへの移行中、応答は、このセクションに記載されているコアプロパティ (EWS と同等のシナリオに必要なプロパティ) に制限されます。このセクションに記載されているプロパティのみを使用することをお勧めします。使用可能なプロパティに対する変更を文書化します。

Get-Mailbox 応答は、JSON オブジェクトまたはメールボックスプロパティを持つリスト配列です。次のプロパティが取得されます。
- ID: メールボックスの正規識別子 (多くの場合、別名または識別名)。
- Id: メールボックスオブジェクトのサービス識別子。
- 名前: メールボックスの一意の Exchange 表示名。
- DisplayName: わかりやすい表示名。
- UserPrincipalName: メールボックスに関連付けられているアカウント。
- エイリアス: 一意のメールボックスエイリアス。
- ExternalDirectoryObjectId: メールボックスのオブジェクト GUID をMicrosoft Entra IDします。
- RecipientType: 可能なメールボックスの値については、「 RecipientType」を参照してください。
- RecipientTypeDetails: 可能なメールボックスの値については、「 RecipientTypeDetails」を参照してください。
- EmailAddresses: 受信者のすべてのプロキシアドレス (SMTP: と smtp: エントリを含む)。
- PrimarySmtpAddress: 受信者のプライマリ SMTP アドレス ( EmailAddresses の SMTP: 値に対応)。
- MaxSendSize: メールボックスが送信できる最大メッセージサイズ。
- GrantSendOnBehalfTo: メールボックスの代理送信アクセス許可を付与された代理人 (SMTP アドレス) の一覧。
- GrantSendOnBehalfToWithDisplayNames: デリゲートの表示名を持つ同じリスト (要求時)。
Set-Mailbox コマンドレットは、成功時にHTTP 200 OKを返します。更新を成功させるために応答本文は必要ありません。

例

例 1: 単純な Get-Mailbox (ページ一覧):

次の使用例は、organization内の最初の 10 個のメールボックスを一覧表示します。続行するには、 @odata.nextLink を使用します。

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
    }
  }
}

例 2: 特定のメールボックスに Get-Mailbox し、代理人の表示名を含めます。

次の使用例は、メールボックスの詳細と SendOnBehalfTo デリゲートと表示名を返します。

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
    }
  }
}

例 3: Set-Mailbox: デリゲートリストを上書きします。

次の使用例は、指定したメールボックスの SendOnBehalfTo リストを指定されたデリゲートで上書きします。

結果は 200 OK です。 delegate1@contoso.com と delegate2@contoso.com メールボックス上の既存の SendOnBehalfTo デリゲートをすべて置き換えます。

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"
      ]
    }
  }
}

例 4: Set-Mailbox: 既存のデリゲートリストにデリゲートを追加する:

次の使用例は、既存のデリゲートを保持しながら、指定したメールボックスに新しい SendOnBehalfTo デリゲートを追加します。

結果は 200 OK です。 delegate3@contoso.com delegate4@contoso.comは、メールボックス上の代理人の既存の一覧に追加されます。

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 2025-11-17