Fichiers, imports et réglages

Cinq espaces de noms couvrent ce qui entoure le courrier lui-même. openemail files est la page Fichiers : chaque pièce jointe envoyée et reçue et chaque fichier téléversé, avec ses octets et les liens de téléchargement sous lesquels il est parti. openemail imports fait entrer une ancienne boîte mail dans une adresse, et openemail provider-imports rapatrie un compte Resend. openemail calendar lit les événements trouvés dans le courrier, et openemail settings lit et modifie les préférences de la boîte mail ainsi que la signature et le suivi de chaque adresse.

• —Un identifiant dit ce qu'il désigne : file_ pour un fichier, imp_ pour un import de boîte mail, pimp_ pour un import Resend et cal_ pour un événement de calendrier, chacun suivi de 24 caractères hexadécimaux. Un lien de téléchargement a son propre identifiant, venant de files list-links ou files create-link.
• —--address-id sur un import est l'identifiant d'une adresse, venant de openemail domains list-addresses <id>, pas l'adresse elle-même.
• —Les espaces de noms répondent aussi à file, import, provider-import ou providerImports, et setting. Les verbes acceptent les alias habituels quand ils en ont : ls pour list, show et view pour get, new et add pour create, edit pour settings update, et rm, del et remove pour files delete.
• —Aucune de ces commandes ne demande de code de vérification à une connexion par navigateur. Celles qui changent quelque chose définitivement demandent confirmation, et --yes répond pour un script.
• —openemail <command> --help liste chaque argument et option avec son type, le scope dont l'appel a besoin, sa méthode et son chemin, et ce qui revient. Ajoutez --json pour obtenir la même page sous forme de données.

openemail files lit et gère chaque fichier de la boîte mail : les pièces jointes reçues, les pièces jointes envoyées, et les fichiers téléversés sur la page Fichiers. openemail open files ouvre la même page dans l'application web.

• —files list filtre avec --q (le nom et le type), --kind (image, pdf, audio, video ou text), --direction (inbound, outbound ou uploaded), --address, --since et --until, et trie avec --sort (newest, oldest, largest ou name). --since et --until prennent une date ou une date-heure ISO 8601 : --since inclut son instant et --until s'arrête avant le sien.
• —Seul un fichier téléversé dont rien ne dépend peut être supprimé, et deletable l'indique à l'avance. usage dit ce qui retient tout autre fichier : received, sent, linked pour un fichier téléversé dont le lien de téléchargement fonctionne encore, ou scheduled pour un fichier joint à un message pas encore parti. delete les refuse avec 409 file_in_use. delete-many supprime ce qu'elle peut, liste le reste dans kept avec une raison pour chacun, et liste les identifiants inconnus dans missing.
• —upload lit le fichier au chemin indiqué et le stocke sous le nom de ce fichier, avec le type qu'implique son extension. --filename et --content-type les remplacent. Depuis stdin, - exige --filename, et sans --content-type le type est application/octet-stream. Le téléversement attend jusqu'à 10 minutes, ce que --timeout-ms modifie.
• —L'identifiant que renvoie upload joint le fichier à un envoi sous la forme { "fileId": "…" } dans openemail emails send --attachments, et c'est ainsi qu'un fichier au-delà de la limite de 5 Mo en ligne peut partir.
• —Un fichier vide donne 400 upload_empty, un programme ou un script (jugé d'après son nom) donne 400 upload_dangerous, et un fichier de plus de 100 Mo donne 413 upload_too_large. Un espace de travail conserve jusqu'à 10 Go de fichiers téléversés et accepte 500 téléversements par heure.
• —download exige --out <file> dans un terminal et s'arrête sans cela avec le code de sortie 2. Quand la sortie est redirigée, les octets vont sur stdout, et --out - demande aussi stdout. Tout le fichier est gardé en mémoire.
• —create-link crée un nouveau lien à chaque appel, avec son propre compteur de téléchargements, et le lien fonctionne jusqu'à sa révocation ou la suppression du fichier. Il se trouve sur le domaine de fichiers de --domain quand ce domaine en a un, comme files.acme.com, sinon sur le domaine de fichiers de l'adresse du fichier, sinon sur l'adresse de l'API. Un programme ou un script est refusé avec 422 file_unshareable.
• —revoke-link peut être répétée sans risque : un lien déjà révoqué revient inchangé.
• —Une clé ou une connexion limitée à certaines adresses ou certains domaines ne voit que les fichiers qui y sont arrivés, jamais ceux téléversés pour tout l'espace de travail, et ses propres fichiers téléversés appartiennent à la première adresse qu'elle détient.
• —L'index des fichiers commence le jour de sa mise en service. Les pièces jointes plus anciennes sont toujours sur leurs messages, où openemail threads list-attachments <id> les lit.

openemail imports fait entrer une ancienne boîte mail dans une adresse : archives Google Takeout, fichiers .mbox d'Apple Mail, de Thunderbird et de la plupart des applications de bureau, fichiers .eml, et archives .zip ou .tgz contenant l'un d'eux, jusqu'à 100 Go par fichier et 50 fichiers par import. Les fils, les dates et les libellés suivent. Le courrier importé est silencieux : il ne déclenche ni règles, ni transferts, ni notifications, ni résumés, ni webhooks.

import-files est celle dont la plupart des gens ont besoin : elle crée l'import, téléverse chaque fichier par parties avec une ligne de progression, et le démarre. Les autres verbes sont ces étapes une à une, pour terminer un téléversement interrompu ou le piloter vous-même. create renvoie le plan, chunkBytes et les chunks de chaque fichier, upload-chunk envoie une partie, upload-state indique quelles parties sont arrivées, et start met l'import en file d'attente. openemail open imports montre les mêmes imports dans l'application web.

• —L'adresse doit se trouver sur les propres domaines de l'espace de travail, et la clé ou la connexion doit pouvoir agir pour elle. Un seul import tourne par adresse : un autre, pendant qu'un premier est en file d'attente ou en cours, donne 409 already_running.
• —import-files prend --files une fois par fichier, ou plusieurs chemins séparés par des virgules, et envoie chacun sous son propre nom de fichier. --options prend du JSON comme {"keepInbox":false,"includeSpam":true}. Sur create, les trois mêmes sont des interrupteurs : --options-keep-inbox, --options-include-spam et --options-include-trash, chacun désactivé avec --no- devant, comme dans --no-options-keep-inbox.
• —keepInbox est activé par défaut, donc le courrier de l'ancienne boîte de réception arrive dans la boîte de réception avec son état non lu. Désactivé, tout est classé dans l'archive. Le spam et la corbeille restent en arrière, sauf si vous les incluez.
• —create prend --files en JSON, en ligne ou depuis un fichier avec @path, et chaque bytes doit être la taille exacte du fichier que vous téléversez ensuite.
• —Chaque partie fait exactement chunkBytes de long, sauf la dernière partie d'un fichier, et une partie de mauvaise longueur donne 400 bad_chunk. start refuse un fichier auquel il manque des parties avec 412 missing_chunks, et un fichier qui n'est ni une archive ni une boîte mail avec 400 unsupported_file. Sur un import qui a déjà quitté uploading, elle renvoie l'import inchangé.
• —Si une partie échoue encore après ses nouvelles tentatives, import-files s'arrête en laissant l'import dans uploading. Le bloc ci-dessous envoie les parties manquantes du premier fichier et le démarre.
• —Un import indique processedBytes sur totalBytes, et counts avec seen, imported, duplicate, filtered, failed et threads. lastError n'est défini que quand status vaut failed.
• —list-failures donne à chaque échec une reason : too-large (plus de 50 Mo), unparseable, no-date, storage-error, unreadable-entry, encrypted-entry ou archive-limit, avec l'objet et l'expéditeur quand ils ont pu être lus.
• —cancel sur un import terminé donne 409 not_cancellable. delete-upload annule un import encore en cours de téléversement, et refuse un import en file d'attente ou en cours avec 409 still_running, annulez donc celui-ci d'abord.

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 rapatrie un espace de travail depuis Resend avec une seule clé API Resend à accès complet. Les suppressions gardent leur motif, les segments deviennent des audiences, les contacts abonnés arrivent avec leurs noms, et les modèles arrivent comme modèles HTML avec leurs variables déclarées. Les webhooks sont enregistrés désactivés, car les livraisons sont signées différemment ici. Une clé de signature ou un jeton ne peut pas quitter Resend, donc les domaines et les clés API reviennent à la place sous forme de liste de contrôle dans le rapport.

• —Passez la clé Resend sous la forme @path pour la lire depuis un fichier, ou - pour la lire depuis stdin, afin qu'elle reste hors de l'historique de votre shell et de la liste des processus. Une clé tapée sur la ligne de commande fonctionne toujours, avec un avertissement. --dry-run affiche le corps avec la clé masquée.
• —--resources accepte n'importe lesquels de suppressions, audiences, contacts, templates, webhooks, domains et api-keys, séparés par des virgules ou répétés.
• —Une clé d'envoi seul donne 400 restricted_key. Créez chez Resend une clé à accès complet pour l'import, et révoquez-la ensuite.
• —inspect lit la première page de chaque ressource et renvoie counts, un { count, more } par ressource, avec more défini quand une ressource dépasse sa première page.
• —Un seul import tourne à la fois par espace de travail, et un second donne 409 already_running. Lancer deux fois le même import ne duplique rien. La clé n'est conservée, chiffrée, que pendant l'import, et elle est effacée quand il se termine, échoue ou est annulé.
• —Les contacts désabonnés chez Resend sont laissés de côté et comptés dans report.contacts.unsubscribed.
• —report.domains liste chaque domaine Resend avec un state : absent quand il n'est pas dans cet espace de travail, added quand il y est mais n'est pas vérifié, et verified, avec les enregistrements qu'il avait chez Resend. Ajoutez un domaine manquant avec openemail domains create. report.apiKeys nomme les clés à recréer avec openemail keys create.
• —Avec une connexion par navigateur, seul le propriétaire de l'espace de travail peut utiliser ces commandes, et un membre reçoit 403 owner_only. Une clé API n'y est pas soumise. Une clé ou une connexion limitée à certaines adresses ou certains domaines ne peut ni inspecter ni créer d'import, puisque les audiences, les suppressions et les modèles appartiennent à tout l'espace de travail.
• —create a aussi besoin du scope de chaque ressource qu'elle importe : audiences:write pour les audiences, contacts:write et audiences:write pour les contacts, templates:write pour les modèles, webhooks:write pour les webhooks et domains:read pour les domaines.

openemail calendar lit les événements de calendrier trouvés dans le courrier. Les trois commandes ne font que lire. list-events déploie chaque événement en ses occurrences dans une période que vous donnez, si bien qu'une réunion hebdomadaire fait une ligne par semaine, et get-event et get-event-ics lisent un événement en entier. openemail open calendar ouvre le calendrier dans l'application web.

• —--from et --to sont des dates-heures ISO 8601 comme 2026-10-01T00:00:00Z. --to doit être après --from et au plus 366 jours plus tard, puisqu'une série récurrente n'a pas de fin jusqu'à laquelle lister. Une borne manquante donne 422 invalid_parameter. Une borne illisible, une période inversée ou trop longue, ou un fuseau inconnu donne 400 invalid_parameter.
• —--timezone est un fuseau IANA comme Europe/London, UTC quand il est omis. Il sert à déployer les événements stockés sans fuseau propre, ce qui décide du jour où tombe un événement sur la journée entière.
• —get-event et get-event-ics prennent l'eventId d'une occurrence, pas l'uid iCalendar. Une série récurrente est un seul événement, donc ses start et end décrivent la première instance.
• —Les événements annulés sont listés aussi, avec status à CANCELLED. myPartstat est la réponse enregistrée pour n'importe quelle adresse que l'espace de travail détient sur ses propres domaines, et null quand aucune d'elles n'est participante.
• —La pagination se poursuit avec --cursor et la même période. Une clé ou une connexion limitée à certaines adresses ne voit que les événements que l'une d'elles organise ou auxquels elle participe, et tout autre événement donne un 404.
• —get-event-ics déclare METHOD:PUBLISH, donc l'importer montre l'événement tel qu'il est plutôt que de proposer de l'accepter ou de le refuser. Les événements horodatés sont écrits comme des instants UTC et les événements sur la journée entière comme des dates. DTSTAMP est l'heure du téléchargement, donc deux téléchargements d'un événement inchangé diffèrent sur cette ligne.

openemail settings lit et modifie les préférences de la boîte mail, comme le fuseau horaire, la langue, le format de l'heure et les listes de blocage. Quatre réglages appartiennent à une adresse plutôt qu'à l'espace de travail : signature, openEmailSignature (le pied de page OpenEmail), trackOpens et trackClicks. Nommez l'adresse avec --address, ou *@acme.com pour le catch-all d'un domaine.

• —Sans --address, get lit les quatre réglages par adresse comme les valeurs par défaut intégrées : pas de signature, le pied de page OpenEmail activé, et le suivi des ouvertures et des liens activé. Avec, ils viennent des valeurs propres à l'adresse, puis du catch-all de son domaine quand le catch-all a recueilli cette adresse, puis des valeurs par défaut. Une adresse plus sans réglages propres lit ceux de son adresse de base.
• —Sans --address, update refuse --signature, --open-email-signature, --track-opens et --track-clicks avec 422 address_required et n'écrit rien. Avec, update n'accepte que ces quatre-là, et tout le reste donne 422 not_per_address. L'adresse doit appartenir à cet espace de travail, ou être *@domain pour un domaine vérifié ici avec son catch-all activé.
• —Les interrupteurs se désactivent avec --no- devant : --no-open-email-signature, --no-track-opens et --no-track-clicks.
• —--signature est du HTML d'au plus 150 000 caractères, assaini à l'écriture, donc ce qui revient est ce qui sera envoyé. Une chaîne vide la retire. C'est l'envoi qui décide s'il l'ajoute : voir --signature dans openemail emails send --help.
• —Les options couvrent les champs courants. --data accepte n'importe quel réglage stocké en JSON, en ligne, depuis un fichier avec @path ou depuis stdin avec -, comme timeFormat, weekStart, undoSendEnabled, blockedSenders ou blockedDomains. Les clés que les réglages ne connaissent pas sont écartées sans erreur, et une clé connue avec le mauvais type donne 422 invalid_parameter.
• —Une liste comme blockedDomains est remplacée en entier, lisez-la donc d'abord et renvoyez-la avec votre changement, comme le fait l'exemple ci-dessous. Une entrée de liste de blocage trop courte pour faire une règle donne 422 blocklist_entry_too_broad.
• —--timezone et --language sont enregistrés tels quels, sans vérification, vérifiez donc un fuseau ou un code de langue avant de l'envoyer.
• —Les champs de confidentialité, externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords et useDefaultBlockedWords, appartiennent à l'espace de travail. Une clé ou une connexion limitée à certaines adresses ou certains domaines ne peut pas les modifier, et ne peut nommer dans --address qu'une adresse qu'elle détient, ou un catch-all sur un domaine qu'elle détient en entier. Les deux refus donnent 422 capability_unsupported.
• —Une mise à jour vide ne change rien et renvoie les réglages actuels. defaultEmailAlias ne fait que présélectionner l'adresse From dans le compositeur de l'application web, et l'API ne l'utilise jamais pour choisir un expéditeur.

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

Chaque create-link crée un nouveau lien, lancez-la donc une fois et relisez le lien avec list-links. revoke-link l'arrête plus tard, y compris dans le courrier déjà parti.

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[]'

Avec --all dans un pipe, files list affiche un fichier par ligne. xargs -n 100 passe à delete-many au plus 100 identifiants par appel, et tout fichier devenu utilisé entre-temps revient dans kept avec sa raison au lieu de faire échouer l'appel.

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 sur import-files affiche le POST /imports qu'elle enverrait, avec le nom et la taille de chaque fichier, et ne téléverse rien. list-failures lit 100 éléments à la fois : passez le nextCursor affiché comme --after pour la page suivante.

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 -

La simulation affiche le PATCH /settings?address=sales%40acme.com et son corps sans l'envoyer. La ligne du catch-all règle le suivi pour chaque adresse que recueille le catch-all de acme.com, et la dernière ligne ajoute un domaine à la liste de blocage sans retirer les autres.

• —Une connexion ou une clé sans le scope s'arrête avec le code de sortie 4, nomme le scope manquant et explique comment l'obtenir.
• —files revoke-link, files delete, files delete-many, imports cancel, imports delete-upload et provider-imports cancel demandent confirmation. Répondre non sort avec le code 10 et ne change rien. Sans surveillance et sans --yes, elles s'arrêtent avec le code de sortie 2 avant tout envoi.
• —Aucune commande ici ne demande de code de vérification, avec une connexion par navigateur comme avec une clé API, donc --yes est tout ce dont un script a besoin.
• —--dry-run affiche la requête qu'un changement enverrait, avec son corps, et sort avec le code 0 sans l'envoyer ni vous demander de confirmer. Un corps de fichier est affiché sous forme de sa taille et de son type.
• —files list, files list-links, imports list, provider-imports list et calendar list-events lisent une page : --limit prend de 1 à 100 et le serveur en envoie 25 quand elle est omise, et --cursor prend le nextCursor de la page précédente. --all lit chaque page, --max <n> s'arrête après autant d'éléments, et --ndjson, ou --all dans un pipe, affiche un objet JSON par ligne. Avec --json, elles affichent un seul document { items, hasMore, nextCursor }.
• —imports list-failures pagine à sa façon : --after prend le nextCursor de la page précédente, --limit vaut au plus 100, la valeur par défaut, et il n'y a pas de --all. Avec --json, elle affiche { object, data, nextCursor }.
• —Les lectures et les changements qui aboutissent au même résultat deux fois sont relancés après une panne réseau : files revoke-link, imports upload-chunk, imports start et settings update. Tout autre changement est envoyé une seule fois. Après une réponse perdue, regardez avant de réessayer : un second upload stocke une seconde copie et un second create-link crée un second lien, un 404 sur votre second files delete signifie que le premier a fonctionné, et un second delete-many liste dans missing ce que le premier a supprimé.
• —Un refus sort avec le code de son statut : 4 pour un 403, 5 pour un 404, 6 pour un 409, 7 pour un 400 ou un 422, et 8 pour un 429.