Guide

Gmail-API-Suchabfragen: Beispiele

Gmail-API-Suchabfragen-Beispiele für den q-Parameter, Labels, Kategorien, Datumsangaben, Anhänge und rfc822msgid. Direkte API-Syntax im Überblick, dann die Übersetzung häufiger Fälle in unterstützte CLI-Filter.

Written by Qasim Muhammad Staff SRE

Reviewed by Nick Barraclough

Verified — CLI 3.1.11 · last tested May 16, 2026

Wie funktioniert die Gmail-API-Suchabfragesyntax?

Die Gmail-API-Suchabfragesyntax funktioniert, indem ein Gmail-Suchausdruck in den Query-Parameter q von users.messages.list übergeben wird. Google dokumentiert, dass der Parameter dasselbe Abfrageformat wie das Gmail-Suchfeld unterstützt — eine einzige HTTP-Anfrage kann also nach Absender, Empfänger, Betreff, Ungelesen-Status, Datum, Anhangsstatus und Nachrichten-ID filtern.

Die zentrale Einschränkung: messages.list liefert Nachrichten-IDs, keine vollständigen Nachrichtentexte. Die Methode gibt standardmäßig 100 Ergebnisse zurück und akzeptiert bis zu 500 Ergebnisse pro Seite. Eine Suche mit 1.500 Treffern braucht also mindestens 3 List-Aufrufe, bevor Sie überhaupt Inhalte abrufen. Die offizielle users.messages.list-Referenz weist außerdem darauf hin, dass q nicht mit dem Scope gmail.metadata verwendet werden kann.

Dieses minimale Python-Beispiel zeigt die direkte API-Form. Es sucht ungelesene Mails eines Absenders, begrenzt die erste Seite auf 50 IDs und verschiebt das Lesen der Nachrichtentexte auf einen zweiten Schritt. Diese Trennung ist wichtig, weil jeder gelesene Nachrichtentext ein weiterer API-Aufruf ist.

response = service.users().messages().list(
    userId="me",
    q="from:billing@stripe.com is:unread",
    maxResults=50,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

Wie suchen Sie nach Absender, Empfänger, Betreff und Ungelesen-Status?

Gmail-Suchabfragen kombinieren Feldoperatoren in einem String — Absender-, Empfänger-, Betreff- und Ungelesen-Filter können also im selben q-Wert stehen. Das praktische Muster: Halten Sie die Abfrage eng, bevor die Pagination beginnt, denn jedes zusätzliche Ergebnis kann später ein weiterer messages.get-Aufruf werden.

Googles Beispiele enthalten Operatoren wie from:, rfc822msgid: und is:unread. Die Gmail-Oberfläche unterstützt zusätzlich to:, subject:, exakte Phrasen und Negation. Im API-Code sind die Operatoren nur ein URL-codierter String; der Server führt die Suche aus und liefert passende Nachrichten-IDs. Eine Obergrenze von 25 Ergebnissen ist ein guter erster Durchlauf für Agent- oder Cron-Jobs, weil sie genug Kandidaten liefert, ohne das gesamte Postfach zu lesen.

Dieser CLI-Befehl verwendet verifizierte Flags von nylas email search. Die Positionsabfrage lautet invoice, weil der aktuelle Befehl eine Nicht-Wildcard-Abfrage als Betrefftext behandelt; Feldoperatoren wie from: sind Gmail-API-Syntax und keine direkte CLI-Weitergabe. Der Befehl liefert 25 JSON-Ergebnisse für Skripte oder Agent-Tools.

nylas email search "invoice" \
  --from "billing@stripe.com" \
  --unread \
  --limit 25 \
  --json

Wie funktionieren Gmail-Labels und Kategorie-Suchen?

Gmail-Labels sind keine Ordner, sondern Tags, die an vielen Nachrichten erscheinen können — und eine Nachricht kann mehrere Labels gleichzeitig tragen. Google dokumentiert 2 Label-Familien: reservierte SYSTEM-Labels wie INBOX und benutzerdefinierte USER-Labels, die vom Postfachinhaber oder einer Integration erstellt werden.

Der Gmail-Labels-Guide listet gängige System-Labels wie INBOX, SPAM, TRASH, UNREAD, STARRED sowie 5 Kategorie-Labels wie CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES und CATEGORY_FORUMS. Suchabfragen verwenden oft die nutzerfreundliche Syntax wie category:promotions, während API-Label-Filter Label-IDs wie CATEGORY_PROMOTIONS verwenden.

Das CLI stellt Gmail-Kategorie-Labels über dieselbe ordnerartige Oberfläche bereit, die auch für andere Provider gilt. Dieses Beispiel sucht 25 Nachrichten im Tab Werbung und führt dann eine Betreffsuche über die Nachrichten im Tab Soziale Netzwerke aus. Beide Befehle verwenden --in, den verifizierten Ordnerfilter von nylas email search.

nylas email search "*" --in "CATEGORY_PROMOTIONS" --limit 25 --json

nylas email search "webinar" \
  --in "CATEGORY_SOCIAL" \
  --limit 25 \
  --json

Wie suchen Sie nach Anhängen, ohne zuerst MIME zu dekodieren?

Gmail-Anhangssuchen sollten mit dem Suchindex beginnen, nicht mit MIME-Parsing. Die Abfrage has:attachment grenzt die Ergebnismenge ein, bevor Ihr Code Nachrichten-Payloads herunterlädt. So vermeiden Sie, jede Nachricht eines großen Postfachs zu dekodieren, nur um festzustellen, dass lediglich 3 Nachrichten Dateien enthalten.

Der Anhang-Download ist trotzdem ein zweiter API-Schritt. Die Gmail-Attachment-Ressource beschreibt attachmentId als den Wert für eine separate messages.attachments.get-Anfrage; die zurückgegebenen Daten sind base64url-codiert. Eine direkte Gmail-Integration braucht also Suche, das Durchlaufen der Nachrichtenteile, das Nachschlagen der Anhang-ID, Byte-Dekodierung und das Schreiben der Datei.

Das CLI hält den ersten Durchlauf klein und verzögert den Datei-Download, bis Sie eine Nachricht und eine Anhang-ID ausgewählt haben. Diese 3 Befehle suchen Nachrichten mit Anhängen, listen die Anhänge einer ausgewählten Nachricht auf und laden dann einen bestimmten Anhang in einen lokalen Pfad herunter.

nylas email search "*" --has-attachment --from "billing@stripe.com" --limit 25 --json

nylas email attachments list <message-id> --json

nylas email attachments download <attachment-id> <message-id> --output ./invoice.pdf

Wie durchsuchen Sie Datumsbereiche und alte E-Mails?

Gmail-Datumssuchen verwenden Operatoren wie after:, before:, older: und newer: innerhalb des Suchausdrucks, während das CLI Datumsgrenzen als explizite Flags bereitstellt. Beide Ansätze sollten für Automatisierung feste Datumsangaben verwenden, damit derselbe Job bei Wiederholungen im 24-Stunden-Rhythmus reproduzierbare Ergebnisse liefert.

Feste Zeitfenster verhindern versteckte Postfach-Scans. Ein monatlicher Rechnungs-Job kann ausschließlich den Januar 2026 durchsuchen und ausgewählte Nachrichten erst lesen, nachdem Betreff und Absender bewertet wurden. Im API-Code steht der Datumsbereich innerhalb des q-Strings. Im CLI machen --after und --before die Datumsgrenzen für Reviewer sichtbar und in einem Wrapper leicht durchsetzbar.

Dieser Befehl sucht Nachrichten mit Rechnungsbetreff zwischen dem 1. Januar und dem 1. Februar 2026. Er liefert höchstens 50 Kandidaten — genug für einen Bericht oder eine Bewertungsrunde eines Agenten, ohne dass der Abrufschritt auf Tausende Nachrichtentexte anwächst.

nylas email search "invoice" \
  --after 2026-01-01 \
  --before 2026-02-01 \
  --limit 50 \
  --json

Wie finden Sie eine einzelne Nachricht mit rfc822msgid?

Der Operator rfc822msgid: sucht nach einer bestimmten Internet-Message-ID. Das ist nützlich, wenn ein Webhook, ein Bounce, eine Log-Zeile oder ein Support-Ticket den ursprünglichen Message-ID-Header festhält. Statt nach Betreff zu scannen, zielt die Suche auf einen global eindeutigen Bezeichner, der normalerweise auf 1 Konversation verweist.

Google führt rfc822msgid: in den Dokumentationsbeispielen zu users.messages.list auf. Der Operator ist beim Debuggen doppelter Sendevorgänge, von Webhook-Fan-out und Antwort-Threading am nützlichsten, weil er die unscharfe Textsuche umgeht. Das Ergebnis kann trotzdem mehr als 1 Nachricht enthalten, wenn Kopien über Labels oder Thread-Ansichten existieren — halten Sie das Limit niedrig und prüfen Sie die IDs, bevor Sie Nachrichtentexte lesen.

Das CLI bietet derzeit keine direkte Gmail-q-Weitergabe für rfc822msgid:. Verwenden Sie für genau diesen Operator die Gmail API direkt, und nutzen Sie CLI-Flags nur, wenn sich die Suche über Absender-, Betreff-, Datums-, Ordner- oder Anhangsfilter annähern lässt. Dieses Beispiel begrenzt die API-Ergebnismenge auf 5 IDs.

response = service.users().messages().list(
    userId="me",
    q="rfc822msgid:<20260516.12345@example.com>",
    maxResults=5,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

Wie blättern Sie sicher durch Gmail-Suchergebnisse?

Sichere Gmail-Such-Pagination hält die Abfrage stabil, speichert das aktuelle nextPageToken und stoppt, sobald die fachliche Obergrenze erreicht ist. Die API erlaubt bis zu 500 Ergebnisse pro Seite, doch Produktions-Jobs sollten üblicherweise eine kleinere Gesamtgrenze wie 200 oder 1.000 Nachrichten definieren.

Bei der Pagination wächst direkter API-Code schnell. Sie brauchen eine Schleife für nextPageToken, eine Ergebnisobergrenze, Retry-Verhalten bei vorübergehenden Fehlern und eine Möglichkeit, fortzusetzen, ohne dieselbe Seite zweimal zu verarbeiten. Wenn ein täglicher Job nur die neuesten 200 Belege braucht, erhöht das Abrufen von 2.000 Treffern Kontingentkosten und Prüfaufwand, ohne das Ergebnis zu verbessern.

Diese Python-Schleife hält die Suchabfrage konstant und stoppt nach 200 Nachrichten-IDs. Sie zeigt den zusätzlichen Zustand, den eine direkte Integration verwalten muss, bevor sie überhaupt messages.get für Betreffzeilen, Snippets oder Nachrichtentexte aufrufen kann.

query = "from:billing@stripe.com has:attachment after:2026/01/01"
page_token = None
message_ids = []

while len(message_ids) < 200:
    response = service.users().messages().list(
        userId="me",
        q=query,
        maxResults=min(100, 200 - len(message_ids)),
        pageToken=page_token,
    ).execute()

    message_ids.extend(message["id"] for message in response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

Wie machen Sie aus Gmail-Suchergebnissen lesbare Nachrichten?

Gmail-Suchergebnisse werden erst nach einem zweiten Abrufschritt lesbar, weil messages.list nur leichtgewichtige Nachrichtendatensätze liefert. Um Betreff, Absender, Snippet oder Nachrichtentext anzuzeigen, muss der Code messages.get für ausgewählte IDs aufrufen und anschließend Header sowie base64url-codierte Payload-Daten parsen.

Diesen Teil verschweigen viele Beispiele. Eine Suche mit 50 Nachrichten-IDs kann 50 Folgeaufrufe bedeuten, wenn Ihr Workflow jeden Treffer liest. Für Agent-Workflows ist ein sichereres Muster: zuerst suchen, Metadaten bewerten, 1 bis 5 ausgewählte Nachrichten lesen und stoppen. Das CLI spiegelt diese Abrufgrenze mit den getrennten Befehlen nylas email search und nylas email read.

Diese Befehle suchen zuerst und lesen danach eine ausgewählte Nachricht. Diese 2-Schritt-Form ist Absicht: Ein Skript oder Modell kann IDs und Snippets prüfen, bevor es weitere Aufrufe für Nachrichteninhalte ausgibt.

nylas email search "contract" --from legal@example.com --limit 10 --json

nylas email read <message-id> --json

Wie bildet das CLI die Suche über Provider hinweg ab?

Das CLI gibt Entwicklern einen einzigen Suchbefehl, während 6 Provider-Familien eigene Suchmaschinen und Postfachmodelle pflegen. Gmail hat q und Labels, Microsoft-Mail hat Graph-Filterung und Ordner-APIs, und IMAP-Server bieten SEARCH plus Postfachordner. Der nützliche Vertrag ist eine einheitliche Befehlsoberfläche, hinter der das provider-spezifische Verhalten verborgen bleibt.

Das provider-seitige Verhalten in diesem Guide ist anhand der Google-Dokumentation und verifizierter CLI-Hilfe beschrieben, nicht durch einen Live-End-to-End-Test auf jedem Backend. Gmail-exklusive Operatoren wie category:promotions und rfc822msgid: sind hier direkte API-Syntax. Bevorzugen Sie für provider-übergreifende Workflows CLI-Flags wie --from, --to, --subject, --after, --before und --has-attachment.

AnforderungGmail-API-FormCLI-Form
Absendersucheq="from:alice@example.com"nylas email search "*" --from alice@example.com
Ungelesen-Sucheq="is:unread"nylas email search "*" --unread
Anhangssucheq="has:attachment"nylas email search "*" --has-attachment
Datumsfensterq="invoice after:2026/01/01 before:2026/02/01"nylas email search "invoice" --after 2026-01-01 --before 2026-02-01

Wie beeinflussen Labels, Ordner und Kategorien die Suchqualität?

Die Qualität der Gmail-Suche hängt davon ab, das richtige Postfachkonzept zu wählen: Labels, Ordner oder Kategorien. Gmail-Labels sind Many-to-many-Tags, Provider-Ordner sind in der Regel ein einziger Ablageort, und Gmail-Kategorien sind System-Labels, die Google zuweist. Diese 3 Postfachkonzepte zu vermischen ist ein häufiger Grund, warum Suchen zu viele Nachrichten liefern oder erwartete Nachrichten verfehlen.

Verwenden Sie die Volltextsuche, wenn sich die Person an Wörter in der Nachricht erinnert. Verwenden Sie Labels, wenn Ihr Workflow Nachrichten bereits klassifiziert hat. Verwenden Sie Kategorien, wenn das Ziel ein Gmail-Tab wie Werbung oder Soziale Netzwerke ist. Verwenden Sie Ordner, wenn Sie einen provider-neutralen Befehl möchten, der sich auch gut auf Outlook, Exchange, Yahoo, iCloud und IMAP abbilden lässt.

Ein 2-Schritt-Muster ist meist am einfachsten zu debuggen: Erst die verfügbaren Ordner oder Labels auflisten, dann innerhalb des gewählten Ablageorts suchen. So bleibt der Ordnername in den Logs sichtbar, und Sie vermeiden es, ein Gmail-exklusives Label fest zu verdrahten, wo ein provider-übergreifender Workflow die Ordnerabstraktion des CLI verwenden sollte.

Wie testen Sie Gmail-Suchabfragen, bevor ein Job produktiv geht?

Testen Sie Gmail-Suchabfragen mit einer 4-Punkte-Schleife, bevor sie in Cron, CI oder einem Agent-Tool landen: kleines Limit ausführen, IDs prüfen, 1 ausgewählte Nachricht lesen und den exakten Abfrage-String speichern. Das fängt zu breite Suchen ab, bevor sie Hunderte Nachrichtentexte lesen.

Der erste Lauf sollte --limit 5 oder --limit 10 verwenden, nicht die Produktionsobergrenze. Prüfen Sie, ob die neuesten 5 Treffer die erwartete Art von Mail sind, und erweitern Sie das Limit erst, wenn sich Absender-, Datums-, Ordner- und Anhangsfilter korrekt verhalten. Testen Sie für einen monatlichen Job mindestens 2 Datumsfenster: eines mit bekannten Treffern und ein leeres Fenster.

Dieser Smoke-Test hält die Ausgabe klein und leicht prüfbar. Der erste Befehl belegt, dass die Suche eingegrenzt ist; der zweite Befehl liest einen Kandidaten. Wenn die ausgewählte Nachricht falsch ist, korrigieren Sie die Abfrage, bevor Sie Pagination oder Sendelogik ergänzen.

nylas email search "invoice" --from billing@example.com --limit 5 --json

nylas email read <message-id> --json

Wie sollten KI-Agenten die Gmail-Suche sicher nutzen?

KI-Agenten sollten die Gmail-Suche als begrenzten Abrufschritt nutzen, nicht als Erlaubnis, das gesamte Postfach zu lesen. Eine sichere Agent-Schleife sucht eng, begrenzt die Kandidaten, prüft Metadaten, liest nur ausgewählte Nachrichten und holt vor jedem Senden oder jeder destruktiven Aktion eine Freigabe ein.

Der Unterschied ist messbar. Ein Agent, der 25 Nachrichten durchsucht und 3 Nachrichtentexte liest, hat einen deutlich kleineren Prompt-, Kosten- und Datenschutz-Fußabdruck als einer, der zuerst 250 Nachrichtentexte liest. Die Suchabfrage wird zudem zum Audit-Artefakt: Reviewer sehen, ob der Agent nach from:customer@example.com, has:attachment oder einem breiten Begriff wie contract gesucht hat.

Dieses Shell-Muster ist eine gute Grundlage für Agent-Tools. Es sammelt 25 Kandidaten-IDs, lässt einen Bewertungsschritt eine auswählen und liest erst dann den Nachrichteninhalt. Die Befehlsnamen lassen sich sauber Audit-Logs und Befehls-Allowlists zuordnen.

nylas email search "contract" --from customer@example.com --limit 25 --json \
  | jq -r '.[].id' \
  | head -5

nylas email read <selected-message-id> --json

Wann sollten Sie die Gmail API statt des CLI verwenden?

Verwenden Sie die Gmail API direkt, wenn Ihre Anwendung 1 Gmail-exklusive Steuerungsebene braucht: rohe q-Operatoren wie rfc822msgid:, Gmail-Administration, eigene Google-Cloud-Verwaltung, Domain-wide Delegation, Pub/Sub-Watch-Erneuerung oder eine Oberfläche, die Googles OAuth-Flow bereits einbettet. Verwenden Sie das CLI, wenn Sie einen Terminal-Workflow, ein Agent-Tool, einen Cron-Job oder ein Multi-Provider-Skript mit weniger beweglichen Teilen möchten.

Bei der Entscheidung geht es nicht darum, ob die Gmail API gut ist, sondern darum, wer die Infrastruktur verantworten soll. Direkter API-Code verantwortet OAuth-Setup, Abfragekonstruktion, Pagination, Nachrichtenabrufe, base64url-Dekodierung, Retry-Verhalten und Provider-Lock-in. Der CLI-Pfad verantwortet Befehlsauswahl und Ausgabeverarbeitung, während Nylas die Provider-Integration im Hintergrund übernimmt.

Für die meiste Entwickler-Automatisierung: Starten Sie mit dem CLI-Pfad und wechseln Sie erst zu direkten Gmail-API-Aufrufen, wenn Sie das Gmail-exklusive Feature benennen können. Diese Regel verhindert, dass Einmal-Skripte, KI-Agent-Tools und CI-Jobs zu langlebigen OAuth-Clients werden.

Was sollten Sie als Nächstes bauen?