Punto de conexión de buzón en la API de Exchange Online Administración

Nota:

Las características descritas en este artículo están actualmente en versión preliminar, no están disponibles en todas las organizaciones y están sujetas a cambios.

El punto de conexión buzón de la API de Exchange Online Administración le permite ver y administrar enviar en nombre de delegados.

Los casos de uso típicos incluyen:

Enumere los buzones de correo o recupere los detalles de un buzón específico.
Inspeccione la configuración del delegado para SendOnBehalfTo, incluidos los nombres para mostrar opcionales para los delegados.
Actualice Enviar en nombre de los delegados sobrescribiendo la lista de delegados completa o realizando cambios incrementales (agregar o quitar).

La API de Exchange Online Administración proporciona una manera basada en REST de ejecutar cmdlets de PowerShell específicos, reemplazando escenarios heredados de Exchange Web Services (EWS). Para obtener más información, consulte Introducción a la API de Exchange Online Administración.

URL de extremo

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

Sugerencia

Use la dirección URL base del entorno, tal como se describe en Entornos admitidos y direcciones URL base.

Modelo de solicitud

Encabezados

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

Para ver los valores de X-AnchorMailbox , consulte sugerencia de enrutamiento X-AnchorMailbox.

Cuerpo

Get-Mailbox:

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

Set-Mailbox (sobrescribir delegados)::

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

Set-Mailbox (agregar o quitar delegados):

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

Paginación

El parámetro ResultSize del cmdlet Get-Mailbox controla la paginación. De forma predeterminada, se devuelven hasta 1000 resultados.

Si hay más resultados disponibles, la respuesta incluye una @odata.nextLink propiedad con una dirección URL de continuación. Para capturar la página siguiente, emita una nueva solicitud POST a la dirección URL de @odata.nextLink con el mismo cuerpo.

Selección de propiedades

Este punto de conexión admite el parámetro de $select consulta para devolver solo propiedades específicas en la respuesta.

Cmdlets y parámetros admitidos

En la lista siguiente se describen los cmdlets y parámetros admitidos por este punto de conexión. Otros cmdlets del cuerpo de este punto de conexión producen un error.

Get-Mailbox:

Solo los parámetros de Get-Mailbox descritos en la tabla siguiente están disponibles a través del punto de conexión REST:

Parámetro	Obligatorio	Tipo	Descripción
Identidad	Opcional	Cadena	Especifica el buzón sobre el que se va a recuperar información. Los valores válidos son nombre, nombre distintivo, alias, nombre principal de usuario (UPN), GUID u otro identificador único. Si se omite y está sujeto a ResultSize, el cmdlet devuelve todos los buzones.
ResultSize	Opcional	Entero o Ilimitado	Limita el número de resultados devueltos. Los valores válidos son un entero (por ejemplo, 10) o el valor `"Unlimited"`.
IncludeGrantSendOnBehalfToWithDisplayNames	Opcional	Booleano	El valor `True` incluye sendOnBehalfTo delegar entradas con sus nombres para mostrar. NOTA: Este parámetro está en el lanzamiento preconfigurado y es posible que no esté disponible en todas las organizaciones.

Set-Mailbox:

Solo los parámetros de Set-Mailbox descritos en la tabla siguiente están disponibles a través del punto de conexión REST:

Parámetro	Obligatorio	Tipo	Descripción
Identidad	Opcional	Cadena	Especifica el buzón de destino. Los valores válidos son nombre, nombre distintivo, alias, UPN, GUID u otro identificador único.
GrantSendOnBehalfTo	Obligatorio	Colección o tabla hash	Sobrescribir: lista de direcciones SMTP para la lista de delegados completa. Por ejemplo, `["bob@contoso.com","carol@contoso.com"]`. Agregar o quitar: tabla hash con `add` matrices o `remove` para modificar la lista de delegados. Por ejemplo, `{ "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }`.

Información general sobre la respuesta

Nota:

Durante la versión preliminar, el punto de conexión incluye la salida completa del cmdlet Get-Mailbox en la respuesta de la API. Durante la transición a la versión pública, la respuesta se limitará a las propiedades principales enumeradas en esta sección (propiedades necesarias para el escenario equivalente a EWS). Se recomienda usar solo las propiedades enumeradas en esta sección. Documentaremos los cambios en las propiedades disponibles.

La respuesta Get-Mailbox es un objeto JSON o una matriz de lista con propiedades de buzón. Se devuelven las siguientes propiedades:
- Identidad: identificador canónico del buzón de correo (a menudo el alias o el nombre distintivo).
- Identificador: identificador de servicio para el objeto de buzón de correo.
- Nombre: nombre único para mostrar de Exchange para el buzón.
- DisplayName: nombre para mostrar fácil de usar.
- UserPrincipalName: cuenta asociada al buzón.
- Alias: alias de buzón único.
- ExternalDirectoryObjectId: Microsoft Entra ID GUID de objeto para el buzón.
- RecipientType: para ver los posibles valores de buzón de correo, vea RecipientType.
- RecipientTypeDetails: para obtener posibles valores de buzón, vea RecipientTypeDetails.
- EmailAddresses: todas las direcciones proxy del destinatario (incluidas las entradas SMTP: y smtp: ).
- PrimarySmtpAddress: dirección SMTP principal del destinatario (corresponde al valor SMTP: en EmailAddresses).
- MaxSendSize: tamaño máximo de mensaje que puede enviar el buzón.
- GrantSendOnBehalfTo: lista de delegados (direcciones SMTP) a los que se conceden permisos send on behalf para el buzón.
- GrantSendOnBehalfToWithDisplayNames: misma lista con nombres para mostrar delegados (cuando se solicita).
El cmdlet Set-Mailbox devuelve HTTP 200 OK correctamente. No se requiere ningún cuerpo de respuesta para las actualizaciones correctas.

Ejemplos

Ejemplo 1: Get-Mailbox simple (lista paginada):

En este ejemplo se enumeran los primeros 10 buzones de correo de la organización. Use @odata.nextLink para continuar.

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

Ejemplo 2: Get-Mailbox para un buzón específico e incluir nombres para mostrar delegados:

En este ejemplo se devuelven los detalles del buzón y los delegados SendOnBehalfTo con nombres para mostrar.

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

Ejemplo 3: Set-Mailbox: Sobrescribir la lista de delegados:

En este ejemplo se sobrescribe la lista SendOnBehalfTo en el buzón especificado con los delegados especificados.

El resultado es: 200 OK. delegate1@contoso.com y delegate2@contoso.com reemplace todos los delegados SendOnBehalfTo existentes en el buzón.

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

Ejemplo 4: Set-Mailbox: Agregar delegados a la lista de delegados existente:

En este ejemplo se agregan nuevos delegados SendOnBehalfTo al buzón especificado y se conservan los delegados existentes.

El resultado es: 200 OK. delegate3@contoso.com y delegate4@contoso.com se agregan a la lista existente de delegados en el buzón de correo.

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

Compartir a través de