Fils, brouillons et libellés

Les commandes de courrier, comme inbox, read, archive et label add, sont écrites pour des personnes : elles prennent plusieurs identifiants de fil à la fois, mettent en forme ce qu'elles affichent et gardent les identifiants de libellé hors de vue. Chacune exécute des commandes de cette page, qui sont les méthodes du SDK pour les fils, les brouillons et les libellés, une commande par méthode, donc threads.listAttachments devient openemail threads list-attachments.

Utilisez-les quand vous avez besoin de ce que les commandes de courrier laissent de côté : un fil exactement tel que l'API le renvoie, les fichiers d'un message, les brouillons, et la création, le renommage, le changement de couleur ou la suppression de libellés.

• —openemail thread et openemail draft fonctionnent aussi bien que les noms au pluriel. openemail labels n'a pas de forme au singulier : openemail label est la commande de courrier qui pose des libellés sur des fils.
• —Les verbes acceptent les alias habituels : ls pour list, show et view pour get, new et add pour create, edit pour update, et rm, del et remove pour delete.
• —Chaque option figure dans openemail <namespace> <verb> --help, comme openemail threads list --help.

Les conversations de la boîte mail. Un identifiant de fil comme CAHk7pQ2x9LmZ4 vient de threads list, openemail inbox ou openemail search.

• —--folder vaut inbox par défaut et est comparé comme un identifiant de libellé, donc sent, archive, spam, trash, draft, snoozed, starred et unread fonctionnent, bin se lit comme trash, et un identifiant de libellé utilisateur comme USER_RECEIPTS fonctionne aussi. Un dossier qui ne correspond à rien renvoie une page vide, pas une erreur.
• —--query accepte la syntaxe de recherche de l'application, et in:anywhere cherche dans tous les dossiers. --label-ids filtre davantage, car un fil doit porter le dossier et chaque identifiant passé. --date-from et --date-to lisent le message le plus récent de chaque fil, et les deux bornes sont incluses.
• —threads get inclut les brouillons de réponse non envoyés parmi les messages, marqués isDraft: true, et ouvre aussi un identifiant de brouillon.
• —threads update a besoin de --read, --no-read ou d'un libellé à ajouter ou retirer. Les retraits sont appliqués avant les ajouts. Un identifiant de libellé qui ne désigne aucun libellé est refusé avec label_not_found et rien ne change sur le fil, créez donc d'abord le libellé. TRASH, SNOOZED et DRAFT sont refusés avec label_not_directly_settable : utilisez threads trash et threads snooze.
• —threads trash ne supprime rien, et le fil reste lisible avec threads get, mais aucune commande ne ressort un fil de la corbeille. Mettre à la corbeille un fil en veille annule aussi son réveil.
• —threads snooze envoie <wake-at> tel quel, donnez-lui donc un instant ISO 8601 futur avec Z ou un décalage, car une heure sans l'un ni l'autre est lue dans le fuseau horaire du serveur. Un délai comme 3h est refusé comme invalide. openemail snooze --until 3h accepte un délai. Les fils se réveillent lors d'un passage horaire, jusqu'à environ une heure en retard, et toujours dans la boîte de réception.
• —threads list-attachments renvoie chaque fichier entier dans une seule réponse. Prenez l'identifiant du message dans les messages de threads get. content est une chaîne vide quand les octets stockés sont introuvables, vérifiez donc sa longueur avant de décoder.

Les messages non envoyés enregistrés dans la boîte mail. Un identifiant de brouillon commence par draft-.

• —drafts list --query cherche dans l'objet, l'expéditeur et le début du corps, et ne sort jamais des brouillons. older_than:30d et les autres opérateurs de date lisent la date du dernier enregistrement du brouillon, et to:, cc: et bcc: ne trouvent rien sur un brouillon.
• —Un brouillon est stocké comme un fil portant le libellé DRAFT, donc threads get en ouvre un et openemail inbox draft les liste. drafts get, update et delete refusent un identifiant de fil ordinaire avec un 404.
• —Un simple openemail drafts create enregistre un brouillon vide. Seules les longueurs sont vérifiées : un objet jusqu'à 998 caractères, et --html et --text jusqu'à 1 000 000 chacun, --html étant conservé quand les deux sont définis. Il n'y a pas d'option pour les pièces jointes.
• —drafts update remplace chaque champ que vous envoyez. Une liste remplace entièrement celle qui est stockée, donc --to avec une adresse abandonne les autres, et une mise à jour vide la liste des pièces jointes du brouillon.
• —--thread-id enregistre le fil auquel répond un brouillon, mais le brouillon reste stocké comme un fil à part.
• —Relancer drafts create enregistre un second brouillon, car la commande ne prend pas de clé d'idempotence. Un nom d'affichage contenant une virgule se scinde en deux destinataires invalides, omettez donc la virgule.
• —openemail send --draft <id> --to <address> envoie un brouillon. Le corps vient du brouillon, tout comme l'objet sauf si vous passez --subject, tandis que les destinataires sont ceux que vous nommez. Ne peut pas être combiné avec un corps, --template ou --translate.

Les libellés qu'un fil peut porter. Un identifiant de libellé utilisateur est USER_ suivi du nom avec lequel il a été créé, en majuscules, chaque suite d'espaces devenant _, donc Big Clients devient USER_BIG_CLIENTS.

• —Un identifiant ne change jamais, même après un renommage, stockez donc des identifiants plutôt que des noms.
• —Les libellés système comme INBOX, STARRED et UNREAD ne sont pas listés et ne peuvent être ni modifiés ni supprimés, bien que threads update les accepte. labels get sur l'un d'eux donne un 404.
• —Un espace de travail contient jusqu'à 50 libellés utilisateur. Un nom qu'un autre libellé porte déjà, comparé sans tenir compte de la casse, est refusé avec label_name_taken.
• —Une couleur est une valeur hexadécimale comme #3B82F6 ou un jeton de dégradé comme gradient:sunset. --label-color prend toute la couleur en JSON, et --label-color null l'efface.
• —Un libellé appartient à l'espace de travail, donc le renommer, changer sa couleur ou le supprimer le change pour tout le monde dans cet espace.
• —labels delete ne peut pas être annulé. Recréer un libellé du même nom donne le même identifiant, mais les fils ne le récupèrent pas. Son threadCount dans labels get indique combien de conversations vont le perdre.

• —Une commande de courrier prend plusieurs identifiants de fil et rend compte de chacun, et avec --json elle affiche { results, succeeded, failed }. Une commande de cette page prend un identifiant et affiche ce que renvoie l'API.
• —openemail inbox lit chaque fil qu'elle liste pour montrer qui a écrit en dernier et l'objet. threads list fait une requête par page et n'affiche que des identifiants, ce qui suffit à un pipeline.
• —openemail read transforme un message HTML en texte et marque le fil comme lu. threads get affiche le fil tel que l'API le renvoie et ne change rien.

Marquer un fil comme lu, l'archiver et lui poser un libellé en une seule requête, là où mark read, archive et label add en feraient trois :

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

Créer un libellé et y classer chaque fil correspondant. Redirigé, --all affiche un objet JSON par ligne :

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

Enregistrer un fichier d'un message. Les identifiants des messages se trouvent dans les messages de 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

Rédiger un brouillon, le modifier, le relire, puis l'envoyer :

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]

Faire le ménage dans les brouillons que personne n'a enregistrés depuis 30 jours. La simulation affiche chaque DELETE sans l'envoyer, et --yes répond à la confirmation :

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

Choisir un dégradé dans la palette, prévisualiser le changement, l'appliquer, puis retirer la couleur plus tard :

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

Un scope manquant s'arrête avec le code de sortie 4. Aucune de ces commandes ne demande de code de vérification, que ce soit avec une connexion par navigateur ou avec une clé API.

Une connexion ou une clé limitée à certaines adresses ne voit que les fils qui leur ont été livrés, et tout autre fil donne un 404, comme s'il n'existait pas. Les libellés appartiennent à l'espace de travail, elle voit donc toujours chaque libellé, mais threadCount ne compte que les conversations qu'elle peut voir.

• —threads list, drafts list et labels list lisent une page, de 25 éléments sauf si --limit indique autre chose, jusqu'à 100. --cursor reprend au curseur qu'une page a affiché. Un curseur de fils garde l'ordre dans lequel il a été remis, envoyez donc les mêmes filtres avec lui.
• —--all lit chaque page et --max <n> s'arrête après autant d'éléments. Redirigé ou avec --ndjson, il affiche un objet JSON par ligne, et avec --json un seul document { items, hasMore, nextCursor }.
• —hasMore peut valoir true sur ce qui s'avère être la dernière page, et l'appel suivant ne renvoie alors aucun élément. Un fil qui reçoit du nouveau courrier pendant que vous parcourez les pages passe devant le curseur et n'est pas renvoyé par les pages suivantes, tout comme un brouillon enregistré pendant ce temps.
• —threads trash, drafts delete et labels delete demandent confirmation. Sans surveillance, avec --json, --no-input ou sans terminal, elles s'arrêtent avec le code de sortie 2 et ne changent rien, sauf si vous passez --yes.
• —--dry-run affiche la requête qu'une commande enverrait, avec l'identifiant masqué, et sort avec le code 0 sans l'envoyer ni demander de confirmation. Avec --json, il affiche { dryRun, request }.

--data prend tout le corps en JSON, en ligne, depuis un fichier avec @path ou depuis stdin avec -, et une option passée en plus remplace sa clé.

Une valeur d'option vide est une erreur d'utilisation, donc un champ qu'une valeur vide efface passe plutôt par --data. --label-color null efface la couleur d'un libellé.

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"

La première enregistre le brouillon sans expéditeur, la deuxième le détache du fil auquel il répondait, et la troisième efface ses destinataires.

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

openemail <namespace> <verb> --help montre chaque argument et option avec son type, les scopes dont l'appel a besoin, sa méthode et son chemin, ce qu'il renvoie et les notes de la référence de l'API. Ajoutez --json pour obtenir la même aide sous forme de données.