Freigeben über

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 Stellvertretungen im Auftrag senden anzeigen und verwalten.

Typische Anwendungsfälle sind:

  • Auflisten von Postfächern oder Abrufen von Details für ein bestimmtes Postfach.
  • Überprüfen Sie die Delegatkonfiguration für SendOnBehalfTo, einschließlich optionaler Anzeigenamen für Delegaten.
  • Aktualisieren Sie "Im Auftrag senden"-Delegaten, indem Sie die vollständige Delegatliste überschreiben oder inkrementelle Änderungen vornehmen (Hinzufügen/Entfernen).

Die Exchange Online Admin-API bietet eine REST-basierte Möglichkeit zum Ausführen bestimmter PowerShell-Cmdlets, die legacy-Szenarien für Exchange-Webdienste (EWS) 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.

Anforderungsmodell

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 (Überschreiben von Delegaten):

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

  • Set-Mailbox (Stellvertretungen 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 ResultSize-Parameter 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, stellen Sie eine neue POST-Anforderung an die URL in @odata.nextLink mit demselben Text.

Eigenschaftenauswahl

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 Text 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, zu dem Informationen abgerufen werden sollen. Gültige Werte sind Name, Distinguished Name, Alias, User Principal Name (UPN), GUID oder ein anderer eindeutiger Bezeichner. Wenn keine Angabe erfolgt und ResultSize gilt, gibt das Cmdlet alle Postfächer zurück.
    ResultSize Optional Integer oder Unlimited Schränkt die Anzahl der zurückgegebenen Ergebnisse ein. Gültige Werte sind eine ganze Zahl (z. B. 10) oder der Wert "Unlimited".
    IncludeGrantSendOnBehalfToWithDisplayNames Optional Boolean Der Wert True enthält SendOnBehalfTo-Delegateinträge mit ihren Anzeigenamen.

    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, Distinguished Name, Alias, UPN, GUID oder ein anderer eindeutiger Bezeichner.
    GrantSendOnBehalfTo Erforderlich Sammlungs- oder Hashtabelle
    • Überschreiben: Liste der SMTP-Adressen für die vollständige Delegatliste. Beispiel: ["bob@contoso.com","carol@contoso.com"].
    • Hinzufügen/Entfernen: Hashtabelle mit add und/oder remove Arrays zum Ändern der Delegatliste. Beispiel: { "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }.

Antwortübersicht

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 ist die Antwort auf die in diesem Abschnitt aufgeführten Kerneigenschaften beschränkt (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 alias oder distinguished name).
    • ID: Dienstbezeichner für das Postfachobjekt.
    • Name: Eindeutiger Exchange-Anzeigename für das Postfach.
    • DisplayName: Benutzerfreundlicher Anzeigename.
    • UserPrincipalName: Konto, das dem Postfach zugeordnet ist.
    • Alias: Eindeutiger Postfachalias.
    • 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 Delegaten (SMTP-Adressen), die "Senden im Auftrag" für das Postfach gewährt wurden.
    • GrantSendOnBehalfToWithDisplayNames: Gleiche Liste mit Anzeigenamen von Delegaten (wenn angefordert).

  • Das Cmdlet Set-Mailbox gibt bei 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 im organization aufgelistet. Verwenden Sie @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 enthalten Anzeigenamen von Delegaten:

    In diesem Beispiel werden Postfachdetails und SendOnBehalfTo-Delegaten mit Anzeigenamen zurückgegeben.

    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: Delegatliste überschreiben:

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

    Das Ergebnis ist: 200 OK. delegate1@contoso.com und delegate2@contoso.com ersetzen alle vorhandenen SendOnBehalfTo-Delegaten für das 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: Fügen Sie der vorhandenen Delegatliste Stellvertretungen hinzu:

    In diesem Beispiel werden dem angegebenen Postfach neue SendOnBehalfTo-Delegaten hinzugefügt, wobei die vorhandenen Delegaten beibehalten werden.

    Das Ergebnis ist: 200 OK. delegate3@contoso.com und delegate4@contoso.com werden der vorhandenen Liste der Stellvertretungen für das 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"
      }
    }
  }
}
  • Last updated on