Threads, Entwürfe und Labels

Die Mail-Befehle wie inbox, read, archive und label add sind für Menschen geschrieben: Sie nehmen mehrere Thread-IDs auf einmal, formatieren ihre Ausgabe und halten die Label-IDs aus dem Blick. Jeder von ihnen führt Befehle von dieser Seite aus, und das sind die SDK-Methoden für Threads, Entwürfe und Labels, ein Befehl pro Methode, threads.listAttachments ist also openemail threads list-attachments.

Nutzen Sie diese, wenn Sie brauchen, was die Mail-Befehle auslassen: einen Thread genau so, wie die API ihn zurückgibt, die Dateien einer Nachricht, Entwürfe und das Anlegen, Umbenennen, Umfärben oder Löschen von Labels.

• —openemail thread und openemail draft funktionieren genauso wie die Pluralnamen. openemail labels hat keine Singularform: openemail label ist der Mail-Befehl, der Labels an Threads setzt.
• —Die Verben nehmen die üblichen Aliasse: ls für list, show und view für get, new und add für create, edit für update und rm, del und remove für delete.
• —Jedes Flag steht in openemail <namespace> <verb> --help, etwa openemail threads list --help.

Unterhaltungen im Postfach. Eine Thread-ID wie CAHk7pQ2x9LmZ4 stammt aus threads list, openemail inbox oder openemail search.

• —--folder ist standardmäßig inbox und wird als Label-ID abgeglichen, daher funktionieren sent, archive, spam, trash, draft, snoozed, starred und unread, bin wird als trash gelesen, und eine Benutzer-Label-ID wie USER_RECEIPTS funktioniert auch. Ein Ordner, auf den nichts passt, liefert eine leere Seite, keinen Fehler.
• —--query nimmt die Suchsyntax der App, und in:anywhere durchsucht jeden Ordner. --label-ids grenzt weiter ein, denn ein Thread muss den Ordner und jede übergebene ID tragen. --date-from und --date-to lesen die neueste Nachricht jedes Threads, und beide Grenzen sind eingeschlossen.
• —threads get zählt ungesendete Antwortentwürfe zu den Nachrichten, markiert mit isDraft: true, und öffnet auch eine Entwurfs-ID.
• —threads update braucht --read, --no-read oder ein Label zum Hinzufügen oder Entfernen. Entfernungen werden vor Hinzufügungen angewendet. Eine Label-ID, die kein Label benennt, wird mit label_not_found abgelehnt, und am Thread ändert sich nichts, legen Sie das Label also zuerst an. TRASH, SNOOZED und DRAFT werden mit label_not_directly_settable abgelehnt: Verwenden Sie threads trash und threads snooze.
• —threads trash löscht nichts, und der Thread bleibt mit threads get lesbar, aber kein Befehl holt einen Thread wieder aus dem Papierkorb. Das Verschieben eines zurückgestellten Threads in den Papierkorb bricht auch sein Wecken ab.
• —threads snooze sendet <wake-at> unverändert, geben Sie also einen künftigen ISO-8601-Zeitpunkt mit Z oder einem Offset an, denn eine Zeit ohne beides wird in der Zeitzone des Servers gelesen. Eine Verzögerung wie 3h wird als ungültig abgelehnt. openemail snooze --until 3h nimmt eine Verzögerung. Threads werden bei einem stündlichen Durchlauf geweckt, bis zu etwa einer Stunde zu spät, und immer in den Posteingang.
• —threads list-attachments gibt jede Datei vollständig in einer Antwort zurück. Nehmen Sie die Nachrichten-ID aus den messages von threads get. content ist ein leerer String, wenn die gespeicherten Bytes nicht gefunden werden, prüfen Sie also seine Länge vor dem Dekodieren.

Ungesendete Nachrichten, die im Postfach gespeichert sind. Eine Entwurfs-ID beginnt mit draft-.

• —drafts list --query durchsucht Betreff, Absender und den Anfang des Bodys und verlässt nie die Entwürfe. older_than:30d und die anderen Datumsoperatoren lesen, wann der Entwurf zuletzt gespeichert wurde, und to:, cc: und bcc: treffen bei einem Entwurf nichts.
• —Ein Entwurf wird als Thread mit dem Label DRAFT gespeichert, daher öffnet threads get einen, und openemail inbox draft listet sie auf. drafts get, update und delete lehnen eine gewöhnliche Thread-ID mit einem 404 ab.
• —Ein bloßes openemail drafts create speichert einen leeren Entwurf. Geprüft werden nur Längen: ein Betreff bis 998 Zeichen und --html und --text bis jeweils 1.000.000, wobei --html behalten wird, wenn beide gesetzt sind. Es gibt kein Flag für Anhänge.
• —drafts update ersetzt jedes Feld, das Sie senden. Eine Liste ersetzt die gespeicherte vollständig, --to mit einer Adresse lässt die anderen also fallen, und ein Update leert die Anhangsliste des Entwurfs.
• —--thread-id hält fest, auf welchen Thread ein Entwurf antwortet, aber der Entwurf wird trotzdem als eigener Thread gespeichert.
• —Ein erneutes drafts create speichert einen zweiten Entwurf, weil es keinen Idempotency-Key nimmt. Ein Anzeigename mit einem Komma darin zerfällt in zwei kaputte Empfänger, lassen Sie das Komma also weg.
• —openemail send --draft <id> --to <address> sendet einen Entwurf. Der Body kommt aus dem Entwurf, ebenso der Betreff, außer Sie übergeben --subject, während die Empfänger die sind, die Sie nennen. Es lässt sich nicht mit einem Body, --template oder --translate kombinieren.

Die Labels, die ein Thread tragen kann. Eine Benutzer-Label-ID ist USER_ gefolgt von dem Namen, mit dem es angelegt wurde, in Großbuchstaben, wobei jede Folge von Leerraum zu _ wird, Big Clients ist also USER_BIG_CLIENTS.

• —Eine ID ändert sich nie, auch nicht nach einer Umbenennung, speichern Sie also IDs statt Namen.
• —System-Labels wie INBOX, STARRED und UNREAD werden nicht aufgelistet und lassen sich nicht ändern oder löschen, obwohl threads update sie nimmt. labels get auf eines davon ist ein 404.
• —Ein Workspace fasst bis zu 50 Benutzer-Labels. Ein Name, den ein anderes Label schon hat, ohne Beachtung der Groß- und Kleinschreibung verglichen, wird mit label_name_taken abgelehnt.
• —Eine Farbe ist ein Hex-Wert wie #3B82F6 oder ein Verlaufs-Token wie gradient:sunset. --label-color nimmt die ganze Farbe als JSON, und --label-color null löscht sie.
• —Ein Label gehört dem Workspace, Umbenennen, Umfärben oder Löschen ändert es also für alle darin.
• —labels delete lässt sich nicht rückgängig machen. Ein neues Label mit demselben Namen bekommt dieselbe ID, aber die Threads bekommen es nicht zurück. Sein threadCount in labels get sagt, wie viele Unterhaltungen es verlieren werden.

• —Ein Mail-Befehl nimmt mehrere Thread-IDs und meldet für jede ein Ergebnis, und mit --json gibt er { results, succeeded, failed } aus. Ein Befehl auf dieser Seite nimmt eine ID und gibt aus, was die API zurückgibt.
• —openemail inbox liest jeden Thread, den es auflistet, um zu zeigen, wer zuletzt geschrieben hat, und den Betreff. threads list stellt eine Anfrage pro Seite und gibt nur IDs aus, und mehr braucht eine Pipeline nicht.
• —openemail read macht aus einer HTML-Nachricht Text und markiert den Thread als gelesen. threads get gibt den Thread so aus, wie die API ihn zurückgibt, und ändert nichts.

Einen Thread in einer Anfrage als gelesen markieren, archivieren und mit einem Label versehen, wo mark read, archive und label add drei bräuchten:

openemail threads update CAHk7pQ2x9LmZ4 --read --add-label-ids ARCHIVE,USER_RECEIPTS --remove-label-ids INBOX --json

Ein Label anlegen und jeden passenden Thread darunter ablegen. Weitergeleitet gibt --all ein JSON-Objekt pro Zeile aus:

openemail labels create --name Receipts --color-background-color gradient:meadowopenemail threads list --query "in:anywhere subject:receipt newer_than:1y" --all | jq -r .id | xargs openemail label add --label USER_RECEIPTS

Eine Datei aus einer Nachricht speichern. Die Nachrichten-IDs stehen in den messages von threads get:

openemail threads get CAHk7pQ2x9LmZ4 --json | jq -r ".messages[].id"openemail threads list-attachments CAHk7pQ2x9LmZ4 message_4c1b257a --json | jq -r '.[] | select(.filename == "invoice.pdf") | .content' | base64 --decode > invoice.pdf

Einen Entwurf schreiben, ändern, zurücklesen und dann senden:

DRAFT=$(openemail drafts create --to [email protected] --subject "Engine notes for Thursday" --html "<p>Agenda below.</p>" --json | jq -r .id)openemail drafts update "$DRAFT" --to [email protected],[email protected]openemail drafts get "$DRAFT"openemail send --draft "$DRAFT" --from [email protected] --to [email protected],[email protected]

Entwürfe aufräumen, die seit 30 Tagen niemand gespeichert hat. Der Probelauf gibt jedes DELETE aus, ohne es zu senden, und --yes beantwortet die Bestätigung:

openemail drafts list --query older_than:30d --all | jq -r .id > stale.txtxargs -n 1 openemail drafts delete --dry-run < stale.txtxargs -n 1 openemail drafts delete --yes < stale.txt

Einen Verlauf aus der Palette wählen, die Änderung in der Vorschau ansehen, sie vornehmen und die Farbe später wieder entfernen:

openemail labels list-colors --json | jq -r '.[] | select(.kind == "gradient") | .value'openemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:aurora --dry-runopenemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:auroraopenemail labels update USER_RECEIPTS --label-color null

Ein fehlender Scope bricht mit Exit-Code 4 ab. Keiner dieser Befehle fragt nach einem Bestätigungscode, weder mit einer Browser-Anmeldung noch mit einem API-Schlüssel.

Eine Anmeldung oder ein Schlüssel, die auf einige Adressen beschränkt sind, sehen nur die Threads, die an diese zugestellt wurden, und jeder andere Thread ist ein 404, als gäbe es ihn nicht. Labels gehören dem Workspace, daher sehen sie trotzdem jedes Label, aber threadCount zählt nur die Unterhaltungen, die sie sehen können.

• —threads list, drafts list und labels list lesen eine Seite, 25 Einträge, sofern --limit nichts anderes sagt, bis zu 100. --cursor macht beim Cursor weiter, den eine Seite ausgegeben hat. Ein Thread-Cursor behält die Reihenfolge, in der er ausgegeben wurde, senden Sie also dieselben Filter mit.
• —--all liest jede Seite, und --max <n> hört nach so vielen auf. Weitergeleitet oder mit --ndjson gibt es ein JSON-Objekt pro Zeile aus, und mit --json ein einziges { items, hasMore, nextCursor }-Dokument.
• —hasMore kann auf der Seite true sein, die sich als letzte herausstellt, und der nächste Aufruf liefert dann keine Einträge. Ein Thread, der während des Blätterns neue Mail bekommt, rückt vor den Cursor und wird von späteren Seiten nicht geliefert, ebenso ein Entwurf, der während des Blätterns gespeichert wird.
• —threads trash, drafts delete und labels delete bitten um Bestätigung. Unbeaufsichtigt, mit --json, --no-input oder ohne Terminal, brechen sie mit Exit-Code 2 ab und ändern nichts, außer Sie übergeben --yes.
• —--dry-run gibt die Anfrage aus, die ein Befehl senden würde, mit geschwärzten Anmeldedaten, und endet mit Exit-Code 0, ohne sie zu senden oder um Bestätigung zu bitten. Mit --json gibt es { dryRun, request } aus.

--data nimmt den ganzen Body als JSON, inline, aus einer Datei mit @path oder von stdin mit -, und ein Flag, das Sie zusätzlich übergeben, überschreibt seinen Schlüssel.

Ein leerer Flag-Wert ist ein Nutzungsfehler, ein Feld, das ein leerer Wert leert, geht also stattdessen über --data. --label-color null löscht die Farbe eines Labels.

openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"from":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"threadId":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"to":[]}'openemail drafts create --data @draft.json --subject "Overrides the file"

Der erste speichert den Entwurf ohne Absender, der zweite löst ihn von dem Thread, auf den er antwortete, und der dritte leert seine Empfänger.

openemail threads --helpopenemail threads list --helpopenemail drafts create --help --json

openemail <namespace> <verb> --help zeigt jedes Argument und Flag mit seinem Typ, die Scopes, die der Aufruf braucht, Methode und Pfad, was er zurückgibt, und die Hinweise aus der API-Referenz. Fügen Sie --json hinzu, um dieselbe Hilfe als Daten zu erhalten.