Hilos, borradores y etiquetas

Los comandos de correo, como inbox, read, archive y label add, están escritos para personas: aceptan varios ids de hilo a la vez, dan formato a lo que muestran y mantienen ocultos los ids de las etiquetas. Cada uno ejecuta comandos de esta página, que son los métodos del SDK para hilos, borradores y etiquetas, un comando por método, así que threads.listAttachments es openemail threads list-attachments.

Usa estos cuando necesites lo que los comandos de correo dejan fuera: un hilo exactamente como lo devuelve la API, los archivos de un mensaje, los borradores, y crear, renombrar, cambiar de color o eliminar etiquetas.

• —openemail thread y openemail draft funcionan igual que los nombres en plural. openemail labels no tiene forma singular: openemail label es el comando de correo que pone etiquetas a los hilos.
• —Los verbos aceptan los alias habituales: ls para list, show y view para get, new y add para create, edit para update, y rm, del y remove para delete.
• —Cada opción está en openemail <namespace> <verb> --help, como openemail threads list --help.

Las conversaciones del buzón. Un id de hilo como CAHk7pQ2x9LmZ4 sale de threads list, openemail inbox u openemail search.

• —--folder es inbox por defecto y se compara como un id de etiqueta, así que funcionan sent, archive, spam, trash, draft, snoozed, starred y unread, bin se lee como trash, y también funciona un id de etiqueta de usuario como USER_RECEIPTS. Una carpeta que no coincide con nada devuelve una página vacía, no un error.
• —--query acepta la sintaxis de búsqueda de la app, e in:anywhere busca en todas las carpetas. --label-ids filtra aún más, ya que un hilo debe llevar la carpeta y cada id que pases. --date-from y --date-to leen el mensaje más reciente de cada hilo, y ambos extremos se incluyen.
• —threads get incluye entre los mensajes las respuestas en borrador sin enviar, marcadas con isDraft: true, y también abre un id de borrador.
• —threads update necesita --read, --no-read o una etiqueta que añadir o quitar. Las eliminaciones se aplican antes que las adiciones. Un id de etiqueta que no corresponde a ninguna etiqueta se rechaza con label_not_found y no cambia nada en el hilo, así que crea primero la etiqueta. TRASH, SNOOZED y DRAFT se rechazan con label_not_directly_settable: usa threads trash y threads snooze.
• —threads trash no elimina nada, y el hilo sigue pudiéndose leer con threads get, pero ningún comando saca un hilo de la Papelera. Mover a la Papelera un hilo pospuesto cancela también su reactivación.
• —threads snooze envía <wake-at> tal cual, así que dale un instante ISO 8601 futuro con Z o un desfase, porque una hora sin ninguno se lee en la zona horaria del servidor. Un retraso como 3h se rechaza por no válido. openemail snooze --until 3h acepta un retraso. Los hilos se reactivan en un barrido cada hora, con hasta una hora de retraso, y siempre en la bandeja de entrada.
• —threads list-attachments devuelve cada archivo entero en una sola respuesta. Toma el id del mensaje de los messages de threads get. content es una cadena vacía cuando no se encuentran los bytes guardados, así que comprueba su longitud antes de decodificarlo.

Mensajes sin enviar guardados en el buzón. Un id de borrador empieza por draft-.

• —drafts list --query busca en el asunto, el remitente y el principio del cuerpo, y nunca sale de los borradores. older_than:30d y los demás operadores de fecha leen cuándo se guardó el borrador por última vez, y to:, cc: y bcc: no coinciden con nada en un borrador.
• —Un borrador se guarda como un hilo con la etiqueta DRAFT, así que threads get abre uno y openemail inbox draft los lista. drafts get, update y delete rechazan un id de hilo normal con un 404.
• —Un openemail drafts create sin nada más guarda un borrador en blanco. Solo se comprueban las longitudes: un asunto de hasta 998 caracteres, y --html y --text de hasta 1,000,000 cada uno, y se conserva --html cuando se definen los dos. No hay opción para adjuntos.
• —drafts update sustituye cada campo que envías. Una lista sustituye entera a la guardada, así que --to con una sola dirección quita las demás, y una actualización vacía la lista de adjuntos del borrador.
• —--thread-id registra el hilo al que responde un borrador, pero el borrador se sigue guardando como un hilo propio.
• —Volver a ejecutar drafts create guarda un segundo borrador, porque no acepta clave de idempotencia. Un nombre visible con una coma se divide en dos destinatarios rotos, así que no pongas la coma.
• —openemail send --draft <id> --to <address> envía un borrador. El cuerpo sale del borrador, y también el asunto salvo que pases --subject, mientras que los destinatarios son los que nombras. No se puede combinar con un cuerpo, --template ni --translate.

Las etiquetas que puede llevar un hilo. Un id de etiqueta de usuario es USER_ seguido del nombre con el que se creó, en mayúsculas, con cada tramo de espacios convertido en _, así que Big Clients es USER_BIG_CLIENTS.

• —Un id nunca cambia, ni siquiera tras renombrar, así que guarda ids en lugar de nombres.
• —Las etiquetas del sistema como INBOX, STARRED y UNREAD no se listan y no se pueden cambiar ni eliminar, aunque threads update las acepta. labels get sobre una de ellas da 404.
• —Un espacio de trabajo tiene hasta 50 etiquetas de usuario. Un nombre que ya tiene otra etiqueta, comparado sin distinguir mayúsculas, se rechaza con label_name_taken.
• —Un color es un valor hexadecimal como #3B82F6 o un token de degradado como gradient:sunset. --label-color acepta el color entero como JSON, y --label-color null lo borra.
• —Una etiqueta pertenece al espacio de trabajo, así que renombrarla, cambiarle el color o eliminarla la cambia para todos sus miembros.
• —labels delete no se puede deshacer. Volver a crear una etiqueta con el mismo nombre da el mismo id, pero los hilos no la recuperan. Su threadCount en labels get dice cuántas conversaciones la perderán.

• —Un comando de correo acepta varios ids de hilo e informa sobre cada uno, y con --json muestra { results, succeeded, failed }. Un comando de esta página acepta un solo id y muestra lo que devuelve la API.
• —openemail inbox lee cada hilo que lista para mostrar quién escribió el último y el asunto. threads list hace una solicitud por página y muestra solo ids, que es todo lo que necesita un pipeline.
• —openemail read convierte un mensaje HTML en texto y marca el hilo como leído. threads get muestra el hilo tal como lo devuelve la API y no cambia nada.

Marca un hilo como leído, archívalo y etiquétalo en una sola solicitud, donde mark read, archive y label add harían tres:

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

Crea una etiqueta y archiva debajo de ella cada hilo que coincida. Redirigido, --all muestra un objeto JSON por línea:

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

Guarda un archivo de un mensaje. Los ids de los mensajes están en los 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

Escribe un borrador, cámbialo, vuelve a leerlo y luego envíalo:

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]

Limpia los borradores que nadie ha guardado en 30 días. La simulación muestra cada DELETE sin enviarlo, y --yes responde a la confirmación:

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

Elige un degradado de la paleta, previsualiza el cambio, hazlo y, más tarde, vuelve a quitar el color:

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 que falta se detiene con el código de salida 4. Ninguno de estos comandos pide un código de verificación, ni con un inicio de sesión con el navegador ni con una clave de API.

Un inicio de sesión o una clave limitados a algunas direcciones solo ven los hilos entregados a ellas, y cualquier otro hilo da 404, como si no existiera. Las etiquetas pertenecen al espacio de trabajo, así que se siguen viendo todas, pero threadCount cuenta solo las conversaciones que se pueden ver.

• —threads list, drafts list y labels list leen una página, de 25 salvo que --limit indique otra cosa, hasta 100. --cursor sigue desde el cursor que mostró una página. Un cursor de hilos mantiene el orden en que se entregó, así que envía con él los mismos filtros.
• —--all lee todas las páginas y --max <n> se detiene tras esa cantidad. Redirigido o con --ndjson muestra un objeto JSON por línea, y con --json un único documento { items, hasMore, nextCursor }.
• —hasMore puede ser true en lo que resulta ser la última página, y la siguiente llamada no devuelve entonces ningún elemento. Un hilo que recibe correo nuevo mientras paginas se adelanta al cursor y las páginas posteriores no lo devuelven, y lo mismo pasa con un borrador guardado mientras paginas.
• —threads trash, drafts delete y labels delete piden que confirmes. Sin supervisión, con --json, --no-input o sin terminal, se detienen con el código de salida 2 y no cambian nada salvo que pases --yes.
• —--dry-run muestra la solicitud que enviaría un comando, con la credencial ocultada, y sale con el código 0 sin enviarla ni pedir confirmación. Con --json muestra { dryRun, request }.

--data recibe el cuerpo entero como JSON, en línea, desde un archivo con @path o desde stdin con -, y una opción que pases además reemplaza su clave.

Un valor de opción vacío es un error de uso, así que un campo que se borra con un valor vacío pasa por --data. --label-color null borra el color de una etiqueta.

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"

El primero guarda el borrador sin remitente, el segundo lo separa del hilo al que respondía y el tercero borra sus destinatarios.

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

openemail <namespace> <verb> --help muestra cada argumento y opción con su tipo, los scopes que necesita la llamada, su método y ruta, lo que devuelve y las notas de la referencia de la API. Añade --json para obtener la misma ayuda como datos.