Nachrichten auflisten

Namespace: microsoft.graph

Mit dieser Methode können Sie die Nachrichten im Postfach des angemeldeten Benutzers abrufen (einschließlich der Nachrichten aus den Ordnern „Gelöschte Elemente“ und „Clutter“).

Je nach Seitengröße und Postfachdaten kann das Abrufen von Nachrichten aus einem Postfach mehrere Anforderungen umfassen. Die standardmäßige Seitengröße beträgt 10 Nachrichten. Verwenden Sie $top, um die Seitengröße anzupassen, mit einem Bereich von 1 bis 1 000.

Verwenden Sie $select, um die Reaktionszeit des Vorgangs zu verbessern und die genauen Eigenschaften anzugeben, die Sie benötigen. Siehe Beispiel 1 unten. Optimieren Sie die Werte für $select und $top, insbesondere wenn Sie eine größere Seitengröße verwenden müssen, da das Zurückgeben einer Seite mit Hunderten von Nachrichten mit jeweils vollständiger Antwortnutzlast eine Gateway-Zeitüberschreitung auslösen kann (HTTP 504).

Um die nächste Seite von Nachrichten abzurufen, wenden Sie einfach die in @odata.nextLink zurückgegebene gesamte URL auf die nächste get-messages-Anforderung an. Diese URL umfasst alle Abfrageparameter, die Sie möglicherweise in der anfänglichen Anforderung angegeben haben.

Versuchen Sie nicht, den $skip-Wert aus der @odata.nextLink-URL zu extrahieren, um Antworten zu bearbeiten. Diese API verwendet den $skip-Wert, um alle Elemente zu zählen, die sie im Postfach des Benutzers durchlaufen hat, um eine Seite von message-type-Elementen zurückzugeben. Daher kann es sein, dass auch in der ersten Antwort der $skip-Wert größer ist als die Seitengröße. Weitere Informationen finden Sie unter Paging der Microsoft Graph-Daten in Ihrer App.

Zurzeit gibt dieser Vorgang Nachrichtentext ausschließlich im HTML-Format zurück.

Es gibt zwei Szenarien, in denen eine App Nachrichten im E-Mail-Ordner eines anderen Benutzers abrufen kann:

  • Wenn die App Anwendungsberechtigungen besitzt oder
  • Wenn die App die entsprechenden delegierten Berechtigungen von einem Benutzer besitzt und ein anderer Benutzer einen E-Mail-Ordner für diesen Benutzer freigegeben hat oder diesem Benutzer delegierten Zugriff erteilt hat. Hier finden Sie weitere Informationen und ein Beispiel.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Mail.ReadBasic Mail.ReadWrite, Mail.Read
Delegiert (persönliches Microsoft-Konto) Mail.ReadBasic Mail.ReadWrite, Mail.Read
Anwendung Mail.ReadBasic.All Mail.ReadWrite, Mail.Read

HTTP-Anforderung

So rufen Sie alle Nachrichten in einem Benutzerpostfach ab:

GET /me/messages
GET /users/{id | userPrincipalName}/messages

So rufen Sie Nachrichten in einem spezifischen Ordner in einem Benutzerpostfach ab:

GET /me/mailFolders/{id}/messages
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages

Optionale Abfrageparameter

Diese Methode unterstützt die OData-Abfrageparameter zur Anpassung der Antwort.

Verwenden von "filter" und "orderby" in derselben Abfrage

Wenn Sie $filter und $orderby in derselben Abfrage verwenden, um Nachrichten abzurufen, stellen Sie sicher, dass Sie Eigenschaften auf folgende Weise angeben:

  1. Eigenschaften, die in $orderby verwendet werden, müssen auch in $filter enthalten sein.
  2. Eigenschaften, die in $orderby verwendet werden, werden in der gleichen Reihenfolge wie in $filter angezeigt.
  3. Eigenschaften, die in $orderby vorhanden sind, werden in $filter vor allen darin nicht vorhandenen Eigenschaften angezeigt.

Wird hiervon abgewichen, kann folgender Fehler auftreten:

  • Fehlercode: InefficientFilter
  • Fehlermeldung: The restriction or sort order is too complex for this operation.

Anforderungsheader

Name Typ Beschreibung
Authorization string Bearer {token}. Erforderlich.
Besser: outlook.body-content-type string Das Format, in der die body- und uniqueBody-Eigenschaften zurückgegeben werden sollen. Werte können „Text“ oder „html“ sein. Wenn die Kopfzeile nicht angegeben ist, werden die body- und uniqueBody-Eigenschaften im HTML-Format zurückgegeben. Optional.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und eine Sammlung von Message-Objekten im Antworttext zurückgegeben.

Beispiele

Beispiel 1: Auflisten aller Nachrichten

Anforderung

In diesem Beispiel wird der Standard abgerufen, also die 10 wichtigsten Nachrichten im Postfach des angemeldeten Benutzers. Hierfür wird $select verwendet, um eine Teilmenge der Eigenschaften der einzelnen Nachrichten in der Antwort zurückzugeben.

GET https://graph.microsoft.com/v1.0/me/messages?$select=sender,subject

Antwort

Das folgende Beispiel zeigt die Antwort. Um die nächste Seite von Nachrichten abzurufen, wenden Sie die in @odata.nextLink zurückgegebene URL auf eine nachfolgende GET-Anforderung an.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages(sender,subject)",
    "value": [
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
            "id": "AAMkAGUAAAwTW09AAA=",
            "subject": "You have late tasks!",
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Planner",
                    "address": "noreply@Planner.Office365.com"
                }
            }
        }
    ]
}