Postfachendpunkt in der Exchange Online Admin API

Hinweis

Die in diesem Artikel beschriebenen Features befinden sich derzeit in der Vorschauphase, sind nicht in allen Organisationen verfügbar und können sich ändern.

Mit dem Postfachendpunkt in der Exchange Online Admin-API können Sie "Senden im Auftrag von"-Stellvertretungen anzeigen und verwalten.

Typische Anwendungsfälle sind:

Auflisten von Postfächern oder Abrufen von Details zu einem bestimmten Postfach.
Überprüfen Sie die Delegatenkonfiguration für SendOnBehalfTo, einschließlich optionaler Anzeigenamen für Stellvertretungen.
Aktualisieren Sie "Senden im Auftrag von", indem Sie die vollständige Stellvertreterliste überschreiben oder inkrementelle Änderungen vornehmen (hinzufügen/entfernen).

Die Exchange Online Admin-API bietet eine REST-basierte Möglichkeit, bestimmte PowerShell-Cmdlets auszuführen und ältere Exchange-Webdienstszenarien (Exchange Web Services, EWS) zu ersetzen. Weitere Informationen finden Sie unter Übersicht über die Exchange Online Admin-API.

Endpunkt-URL

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

Tipp

Verwenden Sie die Basis-URL für Ihre Umgebung, wie unter Unterstützte Umgebungen und Basis-URLs beschrieben.

Modell anfordern

Header

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

Informationen zu X-AnchorMailbox-Werten finden Sie unter X-AnchorMailbox-Routinghinweis.

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 (Delegierte hinzufügen/entfernen):

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

Paginierung

Der Parameter ResultSize im Cmdlet Get-Mailbox steuert die Paginierung. Standardmäßig werden bis zu 1.000 Ergebnisse zurückgegeben.

Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort eine @odata.nextLink Eigenschaft mit einer Fortsetzungs-URL. Um die nächste Seite abzurufen, senden Sie eine neue POST-Anforderung an die URL mit @odata.nextLink demselben Text.

Eigenschaftsauswahl

Dieser Endpunkt unterstützt den $select Abfrageparameter, um nur bestimmte Eigenschaften in der Antwort zurückzugeben.

Unterstützte Cmdlets und Parameter

In der folgenden Liste werden die Cmdlets und Parameter beschrieben, die von diesem Endpunkt unterstützt werden. Andere Cmdlets im Textkörper dieses Endpunkts führen zu einem Fehler.

Get-Mailbox:

Nur die in der folgenden Tabelle beschriebenen Parameter für Get-Mailbox sind über den REST-Endpunkt verfügbar:

Parameter	Erforderlich	Typ	Beschreibung
Identität	Optional	Zeichenfolge	Gibt das Postfach an, über das Informationen abgerufen werden sollen. Gültige Werte sind Name, definierter Name, Alias, Benutzerprinzipalname (UPN), GUID oder ein anderer eindeutiger Bezeichner. Wenn er ausgelassen wird und ResultSize unterliegt, gibt das Cmdlet alle Postfächer zurück.
ResultSize	Optional	Ganze Zahl oder Unbegrenzt	Begrenzt die Anzahl der zurückgegebenen Ergebnisse. Gültige Werte sind eine ganze Zahl (z. B. 10) oder der Wert `"Unlimited"`.
IncludeGrantSendOnBehalfToWithDisplayNames	Optional	Boolean	Der Wert `True` enthält SendOnBehalfTo delegate entries with their display names. HINWEIS: Dieser Parameter befindet sich im gestaffelten Rollout und ist möglicherweise nicht in allen Organisationen verfügbar.

Set-Mailbox:

Nur die in der folgenden Tabelle beschriebenen Parameter für Set-Mailbox sind über den REST-Endpunkt verfügbar:

Parameter	Erforderlich	Typ	Beschreibung
Identität	Optional	Zeichenfolge	Gibt das Zielpostfach an. Gültige Werte sind Name, definierter Name, Alias, UPN, GUID oder ein anderer eindeutiger Bezeichner.
GrantSendOnBehalfTo	Erforderlich	Sammlung oder Hashtabelle	Überschreiben: Liste der SMTP-Adressen für die vollständige Stellvertreterliste. Beispiel: `["bob@contoso.com","carol@contoso.com"]`. Hinzufügen/Entfernen: Hash-Tabelle mit `add` und/oder `remove` Arrays, um die Delegiertenliste zu ändern. Beispiel: `{ "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }`.

Übersicht über die Antwort

Hinweis

Während der Vorschau enthält der Endpunkt die vollständige Ausgabe des Cmdlets Get-Mailbox in der API-Antwort . Während des Übergangs zur öffentlichen Version wird die Antwort auf die in diesem Abschnitt aufgeführten Kerneigenschaften beschränkt sein (Eigenschaften, die für das EWS-äquivalente Szenario erforderlich sind). Es wird empfohlen, nur die in diesem Abschnitt aufgeführten Eigenschaften zu verwenden. Wir dokumentieren alle Änderungen an den verfügbaren Eigenschaften.

Die Get-Mailbox-Antwort ist ein JSON-Objekt oder ein Listenarray mit Postfacheigenschaften. Die folgenden Eigenschaften werden zurückgegeben:
- Identität: Kanonischer Bezeichner für das Postfach (häufig der Alias oder der definierte Name).
- ID: Dienstbezeichner für das Postfachobjekt.
- Name: Eindeutiger Exchange-Anzeigename für das Postfach.
- DisplayName: Benutzerfreundlicher Anzeigename.
- UserPrincipalName: Mit dem Postfach verknüpftes Konto.
- Alias: Eindeutiger Postfach-Alias.
- ExternalDirectoryObjectId: Microsoft Entra ID-Objekt-GUID für das Postfach.
- RecipientType: Mögliche Postfachwerte finden Sie unter RecipientType.
- RecipientTypeDetails: Mögliche Postfachwerte finden Sie unter RecipientTypeDetails.
- EmailAddresses: Alle Proxyadressen für den Empfänger (einschließlich SMTP- und SMTP:-Einträge).
- PrimarySmtpAddress: Primäre SMTP-Adresse für den Empfänger (entspricht dem SMTP:-Wert in EmailAddresses).
- MaxSendSize: Maximale Nachrichtengröße, die das Postfach senden kann.
- GrantSendOnBehalfTo: Liste der Stellvertretungen (SMTP-Adressen), denen "Senden im Auftrag von"-Berechtigungen für das Postfach erteilt wurde.
- GrantSendOnBehalfToWithDisplayNames: Gleiche Liste mit stellvertretenden Anzeigenamen (bei Bedarf).
Das Cmdlet Set-Mailbox gibt nach Erfolg zurück HTTP 200 OK . Für erfolgreiche Updates ist kein Antworttext erforderlich.

Beispiele

Beispiel 1: Einfache Get-Mailbox (ausgelagerte Auflistung):

In diesem Beispiel werden die ersten 10 Postfächer in der organization aufgelistet. Verwenden Sie dies @odata.nextLink , um fortzufahren.

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

Beispiel 2: Get-Mailbox für ein bestimmtes Postfach und Einschließen von Anzeigenamen für Stellvertretungen:

Dieses Beispiel gibt Postfachdetails und SendOnBehalfTo-Stellvertretungen mit Anzeigenamen zurück.

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

Beispiel 3: Set-Mailbox: Überschreiben der Stellvertreterliste:

In diesem Beispiel wird die SendOnBehalfTo-Liste für das angegebene Postfach mit den angegebenen Stellvertretungen überschrieben.

Das Ergebnis lautet: 200 OK. delegate1@contoso.com und delegate2@contoso.com ersetzen Sie alle/alle vorhandenen SendOnBehalfTo-Stellvertretungen im Postfach.

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

Beispiel 4: Set-Mailbox: Hinzufügen von Stellvertretungen zur vorhandenen Stellvertretungsliste:

Dieses Beispiel fügt dem angegebenen Postfach neue SendOnBehalfTo-Delegaten hinzu, während die vorhandenen Delegaten beibehalten werden.

Das Ergebnis lautet: 200 OK. delegate3@contoso.com und delegate4@contoso.com werden der vorhandenen Liste von Stellvertretungen im Postfach hinzugefügt.

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

Zuletzt aktualisiert um 2026-09-25