Dateien, Importe und Einstellungen

Fünf Namespaces decken ab, was rund um die Mail selbst liegt. openemail files ist die Seite Dateien: jeder gesendete und empfangene Anhang und jede hochgeladene Datei, mit ihren Bytes und den Download-Links, als die sie hinausging. openemail imports bringt ein altes Postfach in eine Adresse, und openemail provider-imports holt ein Resend-Konto herüber. openemail calendar liest die in Mail gefundenen Termine, und openemail settings liest und ändert die Postfach-Einstellungen sowie die Signatur und das Tracking jeder Adresse.

• —Eine ID sagt, was sie benennt: file_ für eine Datei, imp_ für einen Postfach-Import, pimp_ für einen Resend-Import und cal_ für einen Kalendertermin, jeweils gefolgt von 24 Hexzeichen. Ein Download-Link hat eine eigene ID, aus files list-links oder files create-link.
• —--address-id bei einem Import ist die ID einer Adresse, aus openemail domains list-addresses <id>, nicht die Adresse selbst.
• —Die Namespaces hören auch auf file, import, provider-import oder providerImports und setting. Verben nehmen die üblichen Aliasse, wo sie welche haben: ls für list, show und view für get, new und add für create, edit für settings update und rm, del und remove für files delete.
• —Keiner dieser Befehle fragt eine Browser-Anmeldung nach einem Bestätigungscode. Die, die etwas endgültig ändern, bitten um Bestätigung, und --yes antwortet für ein Skript.
• —openemail <command> --help listet jedes Argument und Flag mit seinem Typ, dem Scope, den der Aufruf braucht, Methode und Pfad und dem, was zurückkommt. Fügen Sie --json hinzu, um dieselbe Seite als Daten zu erhalten.

openemail files liest und verwaltet jede Datei im Postfach: eingegangene Anhänge, ausgegangene Anhänge und auf die Seite Dateien hochgeladene Dateien. openemail open files öffnet dieselbe Seite in der Web-App.

• —files list grenzt mit --q (Name und Typ), --kind (image, pdf, audio, video oder text), --direction (inbound, outbound oder uploaded), --address, --since und --until ein und sortiert mit --sort (newest, oldest, largest oder name). --since und --until nehmen ein ISO-8601-Datum oder eine Datumszeit: --since schließt seinen Zeitpunkt ein, und --until endet davor.
• —Nur ein Upload, von dem nichts abhängt, lässt sich löschen, und deletable sagt das im Voraus. usage sagt, was jede andere Datei hält: received, sent, linked für einen Upload, dessen Download-Link noch funktioniert, oder scheduled für einen, der an einer noch nicht versandten Nachricht hängt. delete lehnt diese mit 409 file_in_use ab. delete-many löscht, was es kann, listet den Rest mit je einem Grund in kept und unbekannte IDs in missing.
• —upload liest die Datei unter dem angegebenen Pfad und speichert sie unter dem Namen dieser Datei, mit dem Typ, den ihre Endung nahelegt. --filename und --content-type überschreiben beides. Von stdin braucht - ein --filename, und ohne --content-type ist der Typ application/octet-stream. Der Upload wartet bis zu 10 Minuten, was --timeout-ms ändert.
• —Die ID, die upload zurückgibt, hängt die Datei als { "fileId": "…" } in openemail emails send --attachments an einen Versand an, und so geht eine Datei über dem Inline-Limit von 5 MB hinaus.
• —Eine leere Datei ist 400 upload_empty, ein Programm oder Skript (nach seinem Namen beurteilt) ist 400 upload_dangerous, und eine Datei über 100 MB ist 413 upload_too_large. Ein Workspace behält bis zu 10 GB Uploads und nimmt 500 Uploads pro Stunde an.
• —download braucht in einem Terminal --out <file> und bricht ohne es mit Exit-Code 2 ab. Weitergeleitet gehen die Bytes auf stdout, und --out - verlangt ebenfalls stdout. Die ganze Datei wird im Speicher gehalten.
• —create-link erzeugt bei jedem Aufruf einen neuen Link mit eigener Download-Zahl, und der Link funktioniert, bis er widerrufen oder die Datei gelöscht wird. Er liegt auf der Datei-Domain von --domain, wenn diese Domain eine hat, etwa files.acme.com, sonst auf der Datei-Domain der Adresse der Datei, sonst auf der API-Adresse. Ein Programm oder Skript wird mit 422 file_unshareable abgelehnt.
• —revoke-link lässt sich gefahrlos wiederholen: Ein bereits widerrufener Link kommt unverändert zurück.
• —Ein Schlüssel oder eine Anmeldung, die auf bestimmte Adressen oder Domains beschränkt ist, sieht nur die Dateien, die dort ankamen, nie die für den ganzen Workspace hochgeladenen, und eigene Uploads gehören zur ersten Adresse, die er umfasst.
• —Der Dateiindex beginnt an dem Tag, an dem er ausgeliefert wurde. Ältere Anhänge hängen noch an ihren Nachrichten, wo openemail threads list-attachments <id> sie liest.

openemail imports bringt ein altes Postfach in eine Adresse: Google-Takeout-Archive, .mbox-Dateien aus Apple Mail, Thunderbird und den meisten Desktop-Apps, .eml-Dateien und .zip- oder .tgz-Archive, die eines davon enthalten, bis zu 100 GB pro Datei und 50 Dateien pro Import. Threads, Daten und Labels kommen mit. Importierte Mail ist still: Sie löst keine Regeln, Weiterleitungen, Benachrichtigungen, Zusammenfassungen oder Webhooks aus.

import-files ist der, den die meisten brauchen: Er legt den Import an, lädt jede Datei in Teilen mit einer Fortschrittszeile hoch und startet ihn. Die anderen Verben sind diese Schritte einzeln, um einen abgebrochenen Upload fertigzustellen oder ihn selbst zu steuern. create gibt den Plan zurück, chunkBytes und die chunks jeder Datei, upload-chunk sendet einen Teil, upload-state sagt, welche Teile angekommen sind, und start stellt den Import in die Warteschlange. openemail open imports zeigt dieselben Importe in der Web-App.

• —Die Adresse muss auf den eigenen Domains des Workspace liegen, und der Schlüssel oder die Anmeldung muss für sie handeln dürfen. Pro Adresse läuft nur ein Import: Ein weiterer, während einer in der Warteschlange steht oder läuft, ist 409 already_running.
• —import-files nimmt --files einmal pro Datei oder mehrere durch Kommas getrennte Pfade und sendet jede unter ihrem eigenen Dateinamen. --options nimmt JSON wie {"keepInbox":false,"includeSpam":true}. Bei create sind dieselben drei Schalter: --options-keep-inbox, --options-include-spam und --options-include-trash, jeweils mit vorangestelltem --no- ausgeschaltet, wie in --no-options-keep-inbox.
• —keepInbox ist standardmäßig an, Mail aus dem alten Posteingang landet also mit ihrem Ungelesen-Status im Posteingang. Ausgeschaltet wird alles unter Archiv abgelegt. Spam und Papierkorb bleiben zurück, außer Sie schließen sie ein.
• —create nimmt --files als JSON, inline oder aus einer Datei mit @path, und jedes bytes muss genau die Größe der Datei haben, die Sie dann hochladen.
• —Jeder Teil ist genau chunkBytes lang, außer dem letzten Teil einer Datei, und ein Teil mit falscher Länge ist 400 bad_chunk. start lehnt eine Datei mit fehlenden Teilen mit 412 missing_chunks ab und eine, die weder Archiv noch Postfach ist, mit 400 unsupported_file. Bei einem Import, der uploading schon verlassen hat, gibt es den Import unverändert zurück.
• —Scheitert ein Teil auch nach seinen Wiederholungsversuchen, bricht import-files ab, und der Import bleibt in uploading. Der Block unten sendet die fehlenden Teile der ersten Datei und startet ihn.
• —Ein Import meldet processedBytes von totalBytes und counts mit seen, imported, duplicate, filtered, failed und threads. lastError ist nur gesetzt, wenn status failed ist.
• —list-failures gibt jedem Fehler einen reason: too-large (über 50 MB), unparseable, no-date, storage-error, unreadable-entry, encrypted-entry oder archive-limit, mit Betreff und Absender, wo sie lesbar waren.
• —cancel bei einem abgeschlossenen Import ist 409 not_cancellable. delete-upload bricht einen Import ab, der noch hochlädt, und lehnt einen, der in der Warteschlange steht oder läuft, mit 409 still_running ab, brechen Sie diesen also zuerst ab.

openemail imports get "$import_id" --json > import.jsonopenemail imports upload-state "$import_id" --json > state.jsonchunk=$(jq .chunkBytes import.json)chunks=$(jq '.files[0].chunks' import.json)for i in $(seq 0 $((chunks - 1))); do  jq -e --argjson i "$i" '.received[0] | any(. == $i)' state.json > /dev/null && continue  dd if=takeout-001.zip bs="$chunk" skip="$i" count=1 2> /dev/null |    openemail imports upload-chunk "$import_id" 0 "$i" -doneopenemail imports start "$import_id"

openemail provider-imports holt einen Workspace mit einem einzigen Resend-API-Schlüssel mit Vollzugriff von Resend herüber. Sperreinträge behalten ihren Grund, Segmente werden zu Zielgruppen, angemeldete Kontakte kommen mit ihren Namen, und Vorlagen kommen als HTML-Vorlagen mit deklarierten Variablen. Webhooks werden ausgeschaltet registriert, weil Zustellungen hier anders signiert werden. Ein Signaturschlüssel oder ein Token kann Resend nicht verlassen, daher kommen Domains und API-Schlüssel stattdessen als Checkliste im Bericht zurück.

• —Übergeben Sie den Resend-Schlüssel als @path, um ihn aus einer Datei zu lesen, oder als -, um ihn von stdin zu lesen, damit er nicht in Ihrem Shell-Verlauf und in der Prozessliste landet. Ein auf der Kommandozeile getippter Schlüssel funktioniert weiterhin, mit einer Warnung. --dry-run gibt den Body mit geschwärztem Schlüssel aus.
• —--resources nimmt beliebige von suppressions, audiences, contacts, templates, webhooks, domains und api-keys, durch Kommas getrennt oder wiederholt.
• —Ein reiner Versandschlüssel ist 400 restricted_key. Legen Sie für den Import bei Resend einen Schlüssel mit Vollzugriff an und widerrufen Sie ihn danach.
• —inspect liest die erste Seite jeder Ressource und gibt counts zurück, ein { count, more } pro Ressource, wobei more gesetzt ist, wo eine Ressource über ihre erste Seite hinausgeht.
• —Pro Workspace läuft jeweils ein Import, und ein zweiter ist 409 already_running. Denselben Import zweimal auszuführen verdoppelt nichts. Der Schlüssel wird nur verschlüsselt gehalten, solange der Import läuft, und gelöscht, wenn er endet, scheitert oder abgebrochen wird.
• —Kontakte, die sich bei Resend abgemeldet haben, bleiben draußen und werden in report.contacts.unsubscribed gezählt.
• —report.domains listet jede Resend-Domain mit einem state: absent, wenn sie nicht in diesem Workspace ist, added, wenn sie es ist, aber nicht verifiziert, und verified, mit den Einträgen, die sie bei Resend hatte. Fügen Sie eine fehlende mit openemail domains create hinzu. report.apiKeys nennt die Schlüssel, die mit openemail keys create neu anzulegen sind.
• —Mit einer Browser-Anmeldung darf nur der Eigentümer des Workspace diese Befehle nutzen, und ein Mitglied bekommt 403 owner_only. Für einen API-Schlüssel gilt das nicht. Ein Schlüssel oder eine Anmeldung, die auf bestimmte Adressen oder Domains beschränkt ist, kann keinen Import prüfen oder anlegen, da Zielgruppen, Sperreinträge und Vorlagen dem ganzen Workspace gehören.
• —create braucht außerdem den Scope jeder Ressource, die es hereinholt: audiences:write für Zielgruppen, contacts:write und audiences:write für Kontakte, templates:write für Vorlagen, webhooks:write für Webhooks und domains:read für Domains.

openemail calendar liest die in Mail gefundenen Kalendertermine. Alle drei Befehle lesen nur. list-events entfaltet jeden Termin in seine Vorkommen innerhalb eines Zeitraums, den Sie angeben, sodass ein wöchentliches Meeting eine Zeile pro Woche ist, und get-event und get-event-ics lesen einen Termin vollständig. openemail open calendar öffnet den Kalender in der Web-App.

• —--from und --to sind ISO-8601-Datumszeiten wie 2026-10-01T00:00:00Z. --to muss nach --from liegen und höchstens 366 Tage später, da eine sich wiederholende Serie kein Ende hat, bis zu dem sich auflisten ließe. Eine fehlende Grenze ist 422 invalid_parameter. Eine Grenze, die sich nicht parsen lässt, ein umgekehrter oder zu langer Zeitraum oder eine unbekannte Zone ist 400 invalid_parameter.
• —--timezone ist eine IANA-Zone wie Europe/London, UTC, wenn weggelassen. Sie entfaltet die Termine, die ohne eigene Zone gespeichert sind, und das entscheidet, auf welchen Tag ein ganztägiger Termin fällt.
• —get-event und get-event-ics nehmen die eventId eines Vorkommens, nicht die iCalendar-uid. Eine wiederkehrende Serie ist ein Termin, ihr start und end beschreiben also das erste Vorkommen.
• —Abgesagte Termine werden auch aufgelistet, mit status CANCELLED. myPartstat ist die Antwort, die für eine beliebige Adresse erfasst wurde, die der Workspace auf seinen eigenen Domains hat, und null, wenn keine davon Teilnehmer ist.
• —Geblättert wird mit --cursor und demselben Zeitraum. Ein Schlüssel oder eine Anmeldung, die auf bestimmte Adressen beschränkt ist, sieht nur die Termine, die eine davon organisiert oder besucht, und jeder andere Termin ist ein 404.
• —get-event-ics deklariert METHOD:PUBLISH, ein Import zeigt den Termin also so, wie er ist, statt anzubieten, ihn anzunehmen oder abzulehnen. Termine mit Uhrzeit werden als UTC-Zeitpunkte geschrieben und ganztägige Termine als Daten. DTSTAMP ist die Zeit des Downloads, zwei Downloads eines unveränderten Termins unterscheiden sich also in dieser Zeile.

openemail settings liest und ändert die Postfach-Einstellungen, etwa Zeitzone, Sprache, Zeitformat und die Blocklisten. Vier Einstellungen gehören zu einer Adresse statt zum Workspace: signature, openEmailSignature (die OpenEmail-Fußzeile), trackOpens und trackClicks. Nennen Sie die Adresse mit --address, oder *@acme.com für den Catch-all einer Domain.

• —Ohne --address liest get die vier adressbezogenen Einstellungen als eingebaute Standardwerte: keine Signatur, die OpenEmail-Fußzeile an und Öffnungs- und Link-Tracking an. Mit ihm kommen sie aus den eigenen Werten der Adresse, dann aus dem Catch-all ihrer Domain, wenn der Catch-all diese Adresse aufgefangen hat, dann aus den Standardwerten. Eine Plus-Adresse ohne eigene Einstellungen liest die ihrer Basisadresse.
• —Ohne --address lehnt update --signature, --open-email-signature, --track-opens und --track-clicks mit 422 address_required ab und schreibt nichts. Mit ihm nimmt update nur diese vier, und alles andere ist 422 not_per_address. Die Adresse muss in diesem Workspace sein, oder *@domain für eine hier verifizierte Domain mit eingeschaltetem Catch-all.
• —Die Schalter werden mit vorangestelltem --no- ausgeschaltet: --no-open-email-signature, --no-track-opens und --no-track-clicks.
• —--signature ist HTML mit höchstens 150.000 Zeichen, beim Schreiben bereinigt, sodass das Zurückgelieferte das ist, was gesendet wird. Ein leerer String entfernt sie. Ob ein Versand sie hinzufügt, entscheidet der Versand: siehe --signature in openemail emails send --help.
• —Die Flags decken die üblichen Felder ab. --data nimmt jede gespeicherte Einstellung als JSON, inline, aus einer Datei mit @path oder von stdin mit -, etwa timeFormat, weekStart, undoSendEnabled, blockedSenders oder blockedDomains. Schlüssel, die die Einstellungen nicht kennen, werden ohne Fehler verworfen, und ein bekannter Schlüssel mit falschem Typ ist 422 invalid_parameter.
• —Eine Liste wie blockedDomains wird vollständig ersetzt, lesen Sie sie also zuerst und senden Sie sie mit Ihrer Änderung zurück, wie es das Beispiel unten tut. Ein Blocklisten-Eintrag, der zu kurz für eine Regel ist, ist 422 blocklist_entry_too_broad.
• —--timezone und --language werden wie angegeben gespeichert, ohne Prüfung, prüfen Sie eine Zone oder einen Sprachcode also, bevor Sie ihn senden.
• —Die Datenschutzfelder externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords und useDefaultBlockedWords gehören dem Workspace. Ein Schlüssel oder eine Anmeldung, die auf bestimmte Adressen oder Domains beschränkt ist, kann sie nicht ändern und darf in --address nur eine Adresse nennen, die er umfasst, oder einen Catch-all auf einer Domain, die er vollständig umfasst. Beide Ablehnungen sind 422 capability_unsupported.
• —Ein Update ohne Inhalt ändert nichts und gibt die aktuellen Einstellungen zurück. defaultEmailAlias wählt nur die From-Adresse im Composer der Web-App vor, und die API nutzt es nie, um einen Absender zu wählen.

file_id=$(openemail files upload ./price-list.pdf --json | jq -r .id)openemail files create-link "$file_id" --domain acme.com --json | jq -r .urlopenemail files list-links "$file_id"openemail files download "$file_id" --out copy.pdf

Jedes create-link erzeugt einen neuen Link, führen Sie es also einmal aus und lesen Sie den Link mit list-links zurück. revoke-link stoppt ihn später, auch in bereits versandter Mail.

openemail files list --direction uploaded --all | jq -r 'select(.deletable) | .id' > deletable.txtwc -l < deletable.txtxargs -r -n 100 openemail files delete-many --yes --json < deletable.txt | jq -c '.kept[]'

Mit --all in einer Pipe gibt files list eine Datei pro Zeile aus. xargs -n 100 übergibt delete-many höchstens 100 IDs pro Aufruf, und jede Datei, die inzwischen genutzt wird, kommt mit ihrem Grund in kept zurück, statt den Aufruf scheitern zu lassen.

domain_id=$(openemail domains list --all | jq -r 'select(.domain == "acme.com") | .id')address_id=$(openemail domains list-addresses "$domain_id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail imports import-files --address-id "$address_id" --files ~/Downloads/takeout-001.zip --files ~/Downloads/takeout-002.zip --json > import.jsonimport_id=$(jq -r .id import.json)until openemail imports get "$import_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 60doneopenemail imports get "$import_id" --json | jq '{status, counts, lastError}'openemail imports list-failures "$import_id" --json | jq -r '.data[] | [.reason, .subject] | @tsv'

--dry-run bei import-files gibt das POST /imports aus, das es senden würde, mit Name und Größe jeder Datei, und lädt nichts hoch. list-failures liest jeweils 100: Übergeben Sie den ausgegebenen nextCursor als --after für die nächste Seite.

openemail provider-imports inspect @resend-key.txtopenemail provider-imports create --resend-key @resend-key.txt --resources suppressions,audiences,contacts,templates,webhooks,domains,api-keys --json > resend.jsonpimp_id=$(jq -r .id resend.json)until openemail provider-imports get "$pimp_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 10doneopenemail provider-imports get "$pimp_id" --json | jq '.report | {contacts, domains: [.domains[] | {name, state}], apiKeys: [.apiKeys[].name]}'

openemail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z --timezone Europe/London --all |  jq -r 'select(.status != "CANCELLED") | [.start, .summary, .myPartstat] | @tsv'openemail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 --json | jq '.attendees[] | {email, partstat}'openemail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 --out standup.ics

openemail settings get --address [email protected] --json | jq '{signature, openEmailSignature, trackOpens, trackClicks}'openemail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicks --dry-runopenemail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicksopenemail settings update --address '*@acme.com' --no-track-opensopenemail settings update --timezone Europe/London --language enopenemail settings get --json | jq -c '{blockedDomains: ((.blockedDomains + ["spam.example"]) | unique)}' |  openemail settings update --data -

Der Probelauf gibt das PATCH /settings?address=sales%40acme.com und seinen Body aus, ohne es zu senden. Die Catch-all-Zeile setzt das Tracking für jede Adresse, die der Catch-all von acme.com auffängt, und die letzte Zeile fügt der Blockliste eine Domain hinzu, ohne die anderen fallen zu lassen.

• —Eine Anmeldung oder ein Schlüssel ohne den Scope bricht mit Exit-Code 4 ab, nennt den fehlenden Scope und sagt, wie Sie ihn bekommen.
• —files revoke-link, files delete, files delete-many, imports cancel, imports delete-upload und provider-imports cancel bitten um Bestätigung. Eine Antwort mit Nein endet mit Exit-Code 10 und ändert nichts. Unbeaufsichtigt und ohne --yes brechen sie mit Exit-Code 2 ab, bevor etwas gesendet wird.
• —Kein Befehl hier fragt nach einem Bestätigungscode, weder mit einer Browser-Anmeldung noch mit einem API-Schlüssel, daher braucht ein Skript nur --yes.
• —--dry-run gibt die Anfrage aus, die eine Änderung senden würde, mit ihrem Body, und endet mit Exit-Code 0, ohne sie zu senden oder um Bestätigung zu bitten. Ein Datei-Body wird als seine Größe und sein Typ angezeigt.
• —files list, files list-links, imports list, provider-imports list und calendar list-events lesen eine Seite: --limit nimmt 1 bis 100, und der Server sendet 25, wenn es fehlt, und --cursor nimmt den nextCursor der vorigen Seite. --all liest jede Seite, --max <n> hört nach so vielen Einträgen auf, und --ndjson oder --all in einer Pipe gibt ein JSON-Objekt pro Zeile aus. Mit --json geben sie ein einziges { items, hasMore, nextCursor }-Dokument aus.
• —imports list-failures blättert auf eigene Weise: --after nimmt den nextCursor der vorigen Seite, --limit ist höchstens 100, der Standard, und es gibt kein --all. Mit --json gibt es { object, data, nextCursor } aus.
• —Lesezugriffe und die Änderungen, die zweimal ausgeführt dasselbe Ergebnis haben, werden nach einem Netzwerkfehler wiederholt: files revoke-link, imports upload-chunk, imports start und settings update. Jede andere Änderung wird einmal gesendet. Sehen Sie nach einer verlorenen Antwort nach, bevor Sie es erneut versuchen: Ein zweites upload speichert eine zweite Kopie, und ein zweites create-link erzeugt einen zweiten Link, ein 404 bei Ihrem zweiten files delete bedeutet, dass das erste funktioniert hat, und ein zweites delete-many listet in missing, was das erste gelöscht hat.
• —Eine Ablehnung endet mit dem Code ihres Status: 4 für ein 403, 5 für ein 404, 6 für ein 409, 7 für ein 400 oder ein 422 und 8 für ein 429.