codd-tech/imap-client

Was macht imap-client?

Postfächer über IMAP vom Terminal aus lesen mit myl, einem kleinen Python-CLI-Client. Gepflegt und verteilt von codd-tech. Entwickelt für den Einsatz in OpenClaw und jeder anderen AgentSkills-kompatiblen Runtime (Claude Code, generisch).

myl ist schreibgeschützt und bewusst minimalistisch: es listet, durchsucht und ruft Nachrichten und Anhänge ab. Es versendet keine E-Mails, verwaltet keine Ordner und ändert den Zustand nur, wenn optional Nachrichten als gelesen markiert werden.

Wie Anmeldedaten zu diesem Skill gelangen

Dies ist der wichtigste Abschnitt. Sie geben keine Passwörter auf der Kommandozeile ein. Anmeldedaten leben in Umgebungsvariablen, die die Runtime pro Agentenlauf injiziert. Das Skill liest sie und baut über den Wrapper unter {baseDir}/scripts/imap.sh die richtigen myl-Flags zusammen.

Die vom Wrapper erwarteten Variablen:

Variable	Erforderlich	Zweck
IMAP_USER	ja	Login (normalerweise vollständige E-Mail-Adresse)
IMAP_PASSWORD	ja	App-spezifisches Passwort (siehe references/authentication.md)
IMAP_PROVIDER	nein	Einer von auto (Standard), gmail, yandex, mailru, manual
IMAP_SERVER	nur bei manual	IMAP-Host
IMAP_PORT	nein	Standardwert 993
IMAP_STARTTLS	nein	1 um --starttls zu aktivieren (nur mit Port 143 verwenden)

Einmal setzen, für jede Sitzung verwenden. Wie, hängt von der Runtime ab – references/authentication.md behandelt OpenClaws skills.entries.imap-client.env, generisches Shell-export und eine Fallback-Datei ~/.config/imap-client/credentials. Erfinden Sie kein eigenes Schema; verwenden Sie eines dieser drei.

Wenn der Wrapper erkennt, dass IMAP_USER oder IMAP_PASSWORD fehlt, gibt er die Einrichtungsanweisungen aus und beendet sich, ohne einen Server zu kontaktieren. Das ist das Signal, anzuhalten und den Benutzer durch die Einrichtung der Anmeldedaten zu führen, bevor ein erneuter Versuch unternommen wird.

Arbeitsablauf auf einen Blick

1. Prüfen Sie, ob myl installiert ist. OpenClaw sperrt dieses Skill mit requires.bins: ["myl"], daher sollte es ohne nicht geladen werden. Führen Sie für Nicht-OpenClaw-Runtimes bash {baseDir}/scripts/check_myl.sh aus. Wenn es fehlt, folgen Sie references/installation.md.
2. Bestätigen Sie, dass die Anmeldedaten konfiguriert sind. Führen Sie einmal bash {baseDir}/scripts/imap.sh --count 1 >/dev/null aus. Erfolg bedeutet, dass die Umgebungsvariablen verdrahtet sind und die Verbindung funktioniert. Fehlschlag bedeutet, den Benutzer durch references/authentication.md zu führen.
3. Führen Sie die gewünschte Operation über den Wrapper aus. Auflisten, Suchen, Abrufen nach ID, HTML holen, rohes .eml speichern oder einen Anhang herunterladen.
4. Fassen Sie das Ergebnis zusammen. Geben Sie keine vollständigen rohen E-Mail-Inhalte in den Chat aus, es sei denn, der Benutzer hat darum gebeten.

Jedes myl-Beispiel in diesem Skill geht durch {baseDir}/scripts/imap.sh, das Umgebungsvariablen in die richtigen myl-Flags expandiert. Sie müssen sich nicht --google vs. --auto vs. --server/--port merken; der Wrapper wählt basierend auf IMAP_PROVIDER aus.

Wann was lesen

Aufgabe umfasst …	Lesen Sie
Erkennen oder Installieren von myl, OpenClaw requires.bins-Sperre	references/installation.md
Einrichten von Anmeldedaten, Auswahl des Verbindungsmodus, App-Passwörter für Gmail / Yandex / Mail.ru / iCloud / Fastmail	references/authentication.md
Spezifische CLI-Flags, Auflisten, Suchen, Abrufen, Anhänge, providerspezifische Ordnernamen	references/operations.md
Mehrschritt-Rezepte (z. B. „Finde die Rechnung von Acme vom letzten Monat und speichere das PDF“)	references/recipes.md
Fehler wie SSL-Fehler, „Befehl nicht gefunden“, fehlgeschlagene Autodiscovery, „AUTHENTICATIONFAILED“, Umgebungsvariablen nicht sichtbar für den Wrapper	references/troubleshooting.md

Prinzipien

1. Anmeldedaten erscheinen nie in von Ihnen generierten Befehlen

Da Umgebungsvariablen von der Runtime injiziert werden, behandelt der Wrapper sie intern. Generieren Sie keine Befehle wie myl -p hunter2 oder myl -p "$IMAP_PASSWORD" direkt – beide sind ein Leck. Das erste landet in der Shell-History; das zweite macht das Passwort in /proc/<pid>/cmdline sichtbar, während myl läuft. Verwenden Sie den Wrapper, der das Passwort in seinem eigenen Prozessbereich hält:

bash {baseDir}/scripts/imap.sh --count 5

Der Wrapper übergibt die Anmeldedaten an myl wo möglich über stdin und andernfalls über intern konstruierte Flags – der gleiche Kompromiss wie bei direkter myl-Nutzung, aber das Passwortliteral erscheint nie in einem Befehl, den Sie geschrieben, protokolliert oder dem Benutzer gezeigt haben.

2. Standardmäßig kleine Ergebnismengen

Wenn die Absicht des Benutzers explorativ ist („Gibt es neue Mails?“), übergeben Sie --count 5 oder --count 10. Holen Sie nur auf ausdrücklichen Wunsch größere Fenster. Dies hält die Ausgabe lesbar und vermeidet das Ausgeben sensibler Inhalte, die der Benutzer nicht sehen wollte.

3. Nicht versehentlich als gelesen markieren

--mark-seen ändert den Zustand auf dem Server. Übergeben Sie es nur, wenn der Benutzer ausdrücklich darum gebeten hat, Nachrichten als gelesen zu markieren. Auflisten oder Lesen ohne dieses Flag ist nicht destruktiv.

4. Lange Nachrichtentexte in einer Datei ausgeben, im Chat zusammenfassen

Wenn der Benutzer eine lange Nachricht oder HTML-E-Mail abruft, speichern Sie die Rohausgabe in einer Datei (z. B. /tmp/email-<id>.eml oder .html) und geben Sie dem Benutzer eine Zusammenfassung von 2–4 Sätzen plus den Dateipfad. Fügen Sie keinen 500-zeiligen HTML-Text in die Konversation ein.

5. Die Suchsyntax ist serverseitiges IMAP, nicht die Gmail-Weboberfläche

--search "important" führt einen IMAP-SEARCH-Befehl aus. Es versteht nicht Gmail's from:, has:attachment oder label: Operatoren. Für komplexe Filterungen holen Sie ein angemessenes Fenster mit --count und filtern Sie die Liste lokal. Siehe references/operations.md für Details, was IMAP SEARCH unterstützt.

6. Das Passwort niemals ausgeben, zusammenfassen oder speichern

Wenn Sie zusammenfassen, was Sie getan haben, beziehen Sie sich auf die Anmeldedaten als IMAP_PASSWORD oder „das Passwort aus Ihrer OpenClaw-Konfiguration“, niemals auf den tatsächlichen Wert. Wenn der Benutzer versehentlich ein Passwort in den Chat einfügt, behandeln Sie es als kompromittiert: sagen Sie ihm, er solle es rotieren und seine Konfiguration aktualisieren. Schreiben Sie es nicht in ein Artefakt.

Schnellentscheidungsbaum

Benutzer hat etwas E-Mail-bezogenes über die CLI gefragt
  │
  ├─ Ist `myl` installiert und im PATH?  ── Nein  ──► references/installation.md
  │   │
  │   Ja
  │   ▼
  ├─ Besteht der Wrapper-Smoke-Test?
  │     bash {baseDir}/scripts/imap.sh --count 1 >/dev/null
  │   │                       Nein  ──► references/authentication.md
  │   Ja
  │   ▼
  ├─ Was möchte der Benutzer?
  │   ├─ Durchsuchen / Auflisten    ──► imap.sh --count N [--folder F]
  │   ├─ Suchen                     ──► imap.sh --search "BEGRIFF" [--count N]
  │   ├─ Eine Nachricht lesen        ──► imap.sh "$MAILID"
  │   ├─ HTML-Version lesen          ──► imap.sh --html "$MAILID"  → in Datei speichern
  │   ├─ Roh-.eml speichern          ──► imap.sh --raw "$MAILID" > datei.eml
  │   ├─ Anhang holen                ──► imap.sh "$MAILID" "$ANH_NAME" > datei
  │   └─ Mehrschrittiges Vorgehen    ──► references/recipes.md
  │
  └─ Fehler? ─────────────────────► references/troubleshooting.md

Ausgabestil

Präsentieren Sie die Ergebnisse nach dem Ausführen des Wrappers in dieser Form:

• Einzeiliger Status darüber, was gerade ausgeführt wurde (z. B. „Die 10 neuesten Nachrichten im Posteingang aufgelistet“).
• Eine kompakte Tabelle oder Aufzählungsliste der Nachrichtenmetadaten (Datum, Von, Betreff, ID).
• Alle Dateipfade, in denen größere Ausgaben gespeichert wurden.
• Vorgeschlagene nächste Aktionen (z. B. „Soll ich #4582 öffnen oder seine Anhänge speichern?“).

Halten Sie es überfliegbar.