Guide

Gmail API: Spam- und Papierkorb-Nachrichten auflisten

Ihr Skript listet jede Nachricht im Postfach auf, doch das gesuchte Phishing-Sample taucht nie auf. Das ist kein Bug in Ihrem Code. Die Gmail API schließt SPAM und TRASH standardmäßig aus den messages.list-Ergebnissen aus, sofern Sie sie nicht explizit anfordern. Dieser Guide zeigt die drei dokumentierten Wege, Spam und Papierkorb zu lesen: den Parameter includeSpamTrash, den labelIds-Filter und in:spam-Suchanfragen — plus das Ein-Flag-Äquivalent im CLI.

Written by Aaron de Mello Senior Engineering Manager

Verified — CLI 3.1.16 · Gmail · last tested June 6, 2026

In diesem Guide verwendete Befehlsreferenzen: nylas email list und nylas email folders list.

Warum liefert die Gmail API keine Spam- oder Papierkorb-Nachrichten zurück?

Die Gmail API schließt die Systemlabels SPAM und TRASH standardmäßig aus den Antworten von users.messages.list aus. Der Query-Parameter includeSpamTrash steuert dieses Verhalten, hat den Standardwert false und sorgt laut der messages.list-Referenz bei true dafür, dass "messages from SPAM and TRASH" in den Ergebnissen erscheinen.

Für Inbox-artige Apps ist dieser Standard sinnvoll, doch er bricht drei reale Workloads: Missbrauchs- und Phishing-Analyse, vollständige Postfach-Backups und Skripte zur Wiederherstellung von False Positives. Jeder messages.list-Aufruf kostet 5 Quota-Einheiten und liefert standardmäßig 100 Nachrichten-IDs (500 mit maxResults) — die Lösung ist also eine Parameteränderung, keine zusätzlichen Requests.

Wie nehmen Sie Spam und Papierkorb mit includeSpamTrash auf?

Setzen Sie includeSpamTrash=true auf messages.list, erscheinen Spam- und Papierkorb-Nachrichten neben allem anderen in den Ergebnissen. Der Parameter erweitert die Ergebnismenge, statt sie zu filtern — verwenden Sie ihn, wenn Sie einen vollständigen Postfach-Durchlauf brauchen. Kombiniert mit maxResults=500 deckt ein Request das 5-Fache der Standard-Seitengröße ab.

Das Python-Beispiel unten verwendet google-api-python-client und zählt, wie viele der ersten 500 Ergebnisse das Label SPAM oder TRASH tragen. Beachten Sie: Jedes nachfolgende messages.get kostet 20 Quota-Einheiten, das 4-Fache des List-Aufrufs.

from googleapiclient.discovery import build

service = build("gmail", "v1", credentials=creds)

# Include spam and trash in a full-mailbox listing
results = service.users().messages().list(
    userId="me",
    includeSpamTrash=True,
    maxResults=500,
).execute()

ids = [m["id"] for m in results.get("messages", [])]
print(f"{len(ids)} messages, spam and trash included")

# Check which labels a specific message carries
msg = service.users().messages().get(
    userId="me", id=ids[0], format="minimal"
).execute()
print(msg["labelIds"])  # e.g. ['SPAM'] or ['TRASH']

Ohne den Parameter lässt derselbe Aufruf jede mit SPAM oder TRASH gelabelte Nachricht stillschweigend weg. Es gibt keine Warnung und keine Zählung des Ausgeschlossenen — deshalb melden Backup-Skripte ohne dieses Flag eine zu kleine Postfachgröße und übersehen wiederherstellbare Mails.

Wie listen Sie nur Spam-Nachrichten mit labelIds auf?

Übergeben Sie labelIds=["SPAM"] an messages.list, erhalten Sie ausschließlich Spam-Nachrichten — ganz ohne includeSpamTrash. Die API-Referenz beschreibt den Filter so: Er liefert Nachrichten "with labels that match all of the specified label IDs", eine einzelne Label-ID ergibt also genau diesen Ordner. Für gelöschte Mails verwenden Sie ["TRASH"] auf dieselbe Weise.

Die dritte Option ist der Parameter q, der laut derselben Referenz das Format der Gmail-Suchbox unterstützt ("supports the same query format as the Gmail search box"). Damit ist q="in:spam" äquivalent zum labelIds-Filter und lässt sich mit weiteren Operatoren wie from: und after: in einem String kombinieren.

# Spam only, via labelIds
spam = service.users().messages().list(
    userId="me", labelIds=["SPAM"], maxResults=100
).execute()

# Trash only
trash = service.users().messages().list(
    userId="me", labelIds=["TRASH"], maxResults=100
).execute()

# Search-style: spam from one sender in the last week
recent = service.users().messages().list(
    userId="me", q="in:spam from:billing@suspicious.example newer_than:7d"
).execute()

Wählen Sie nach Absicht: labelIds für einen sauberen Einzelordner-Read, q, wenn Sie den Spam-Scope mit Absender-, Datums- oder Anhangsbedingungen kombinieren müssen. Beide Ansätze kosten dieselben 5 Quota-Einheiten pro List-Aufruf. SPAM und TRASH sind 2 von Gmails 13 eingebauten Systemlabels, aufgeführt im Gmail-Labels-Guide.

Wie lange behält Gmail Nachrichten im Papierkorb?

Gmail bewahrt eine gelöschte Nachricht bis zu 30 Tage im Papierkorb auf. Laut Googles Wiederherstellungs-Dokumentation gilt: "Up to 30 days after deletion: You can find the message in Trash", und nach 30 Tagen: "The message is permanently deleted." Jedes Wiederherstellungsskript, das Sie gegen das TRASH-Label bauen, läuft gegen diese Uhr.

Dieses Zeitfenster bestimmt, wie Sie Automatisierung planen. Ein wöchentlicher Cron-Job, der den Papierkorb nach JSON exportiert, hat 4 Chancen, eine Nachricht zu erwischen, bevor Gmail sie endgültig löscht; ein monatlicher kann Nachrichten komplett verpassen. Für die Spam-Triage gilt dasselbe Muster: Listen Sie das SPAM-Label in einem Rhythmus, der kürzer ist als das Incident-Response-Fenster Ihres Teams, und sichern Sie alles, was Sie als Beweismittel brauchen könnten.

Wie lesen Sie Spam und Papierkorb über das CLI?

Der Befehl nylas email list --folder SPAM liefert Gmail-Spam-Nachrichten als JSON — ohne Google-Cloud-Projekt, OAuth-Consent-Screen oder Python-Client-Setup. Das --folder-Flag des CLI akzeptiert jede Gmail-Systemlabel-ID, TRASH funktioniert also identisch, und --all-folders durchläuft alle Ordner in einem Lauf. Die Authentifizierung erledigt ein einziges nylas auth login.

# List spam messages
nylas email list --folder SPAM --limit 20

# List trash as JSON for scripting
nylas email list --folder TRASH --json --limit 50

# Sweep every folder, spam and trash included
nylas email list --all-folders --json --limit 200

# Extract sender addresses from spam for a blocklist review
nylas email list --folder SPAM --json --limit 50 | \
  jq -r '.[].from[0].email' | sort | uniq -c | sort -rn

Diese Befehle wurden gegen ein Live-Gmail-Konto mit CLI 3.1.16 verifiziert. Dieselbe --folder-Syntax funktioniert mit den jeweiligen Ordnernamen auch für Outlook- und IMAP-Konten — ein für Gmail geschriebenes Spam-Review-Skript läuft so bei anderen Providern, ohne das Label-Modell der Gmail API anzufassen. Führen Sie nylas email folders list aus, um die exakten Ordner-IDs jedes verbundenen Kontos zu sehen.

Nächste Schritte