Exchange Online 관리 API의 사서함 엔드포인트

참고

이 문서에 설명된 기능은 현재 미리 보기로 제공되며, 모든 조직에서 사용할 수 없으며 변경될 수 있습니다.

Exchange Online 관리 API의 사서함 엔드포인트를 사용하면 대리자를 대신하여 보내기를 보고 관리할 수 있습니다.

일반적인 사용 사례는 다음과 같습니다.

사서함을 나열하거나 특정 사서함에 대한 세부 정보를 검색합니다.
대리인에 대한 선택적 표시 이름을 포함하여 SendOnBehalfTo에 대한 대리자 구성을 검사합니다.
전체 대리자 목록을 덮어쓰거나 증분 변경(추가/제거)하여 대리자를 대신하여 보내기를 업데이트합니다.

Exchange Online 관리 API는 특정 PowerShell cmdlet을 실행하는 REST 기반 방법을 제공하여 레거시 EWS(Exchange Web Services) 시나리오를 대체합니다. 자세한 내용은 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 라우팅 힌트를 참조하세요.

본문

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 cmdlet의 ResultSize 매개 변수는 페이지 매김을 제어합니다. 기본적으로 최대 1,000 결과가 반환됩니다.

더 많은 결과를 사용할 수 있는 경우 응답에는 연속 URL이 있는 @odata.nextLink 속성이 포함됩니다. 다음 페이지를 가져오려면 동일한 본문으로 의 URL에 @odata.nextLink 대한 새 POST 요청을 실행합니다.

속성 선택

이 엔드포인트는 응답의 $select 특정 속성만 반환하는 쿼리 매개 변수를 지원합니다.

지원되는 cmdlet 및 매개 변수

다음 목록에서는 이 엔드포인트에서 지원하는 cmdlet 및 매개 변수에 대해 설명합니다. 이 엔드포인트 본문의 다른 cmdlet으로 인해 오류가 발생합니다.

Get-Mailbox:

다음 표에 설명된 Get-Mailbox 에 대한 매개 변수만 REST 엔드포인트를 통해 사용할 수 있습니다.

매개 변수	필수	유형	설명
ID	옵션	String	정보를 검색할 사서함을 지정합니다. 유효한 값은 이름, 고유 이름, 별칭, UPN(사용자 계정 이름), GUID 또는 기타 고유 식별자입니다. 생략되고 ResultSize가 적용되는 경우 cmdlet은 모든 사서함을 반환합니다.
ResultSize	옵션	정수 또는 무제한	반환된 결과 수를 제한합니다. 유효한 값은 정수(예: 10) 또는 값 `"Unlimited"`입니다.
IncludeGrantSendOnBehalfToWithDisplayNames	옵션	부울	값 `True` 에는 표시 이름을 가진 SendOnBehalfTo 대리자 항목이 포함됩니다. 참고: 이 매개 변수는 단계적 롤아웃 중이며 일부 조직에서는 사용할 수 없습니다.

Set-Mailbox:

다음 표에 설명된 Set-Mailbox 에 대한 매개 변수만 REST 엔드포인트를 통해 사용할 수 있습니다.

매개 변수	필수	유형	설명
ID	옵션	String	대상 사서함을 지정합니다. 유효한 값은 이름, 고유 이름, 별칭, UPN, GUID 또는 기타 고유 식별자입니다.
GrantSendOnBehalfTo	필수	컬렉션 또는 해시 테이블	덮어쓰기: 전체 대리자 목록에 대한 SMTP 주소 목록입니다. 예를 들면 `["bob@contoso.com","carol@contoso.com"]`와 같습니다. 추가/제거: 대리자 목록을 수정하기 위해 및/또는 `remove` 배열이 있는 해시 테이블 `add` 입니다. 예를 들면 `{ "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }`와 같습니다.

응답 개요

참고

미리 보기 중에 엔드포인트에는 API 응답에 전체 Get-Mailbox cmdlet 출력이 포함됩니다. 공개 릴리스로 전환하는 동안 응답은 이 섹션에 나열된 핵심 속성(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 cmdlet은 성공 시 반환됩니다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