Conversas, rascunhos e etiquetas

Os comandos de correio, como inbox, read, archive e label add, são escritos para pessoas: aceitam vários ids de conversa de uma vez, formatam o que mostram e mantêm os ids das etiquetas fora de vista. Cada um executa comandos desta página, que são os métodos do SDK para conversas, rascunhos e etiquetas, um comando por método, por isso threads.listAttachments é openemail threads list-attachments.

Use estes quando precisar do que os comandos de correio deixam de fora: uma conversa exatamente como a API a devolve, os ficheiros de uma mensagem, os rascunhos, e criar, mudar o nome, mudar a cor ou eliminar etiquetas.

• —openemail thread e openemail draft funcionam tal como os nomes no plural. openemail labels não tem forma no singular: openemail label é o comando de correio que põe etiquetas nas conversas.
• —Os verbos aceitam os aliases habituais: ls para list, show e view para get, new e add para create, edit para update, e rm, del e remove para delete.
• —Cada opção está em openemail <namespace> <verb> --help, como openemail threads list --help.

As conversas da caixa de correio. Um id de conversa como CAHk7pQ2x9LmZ4 vem de threads list, openemail inbox ou openemail search.

• —--folder é inbox por predefinição e é comparado como um id de etiqueta, por isso funcionam sent, archive, spam, trash, draft, snoozed, starred e unread, bin é lido como trash, e um id de etiqueta de utilizador como USER_RECEIPTS também funciona. Uma pasta que não corresponde a nada devolve uma página vazia, não um erro.
• —--query aceita a sintaxe de pesquisa da aplicação, e in:anywhere pesquisa em todas as pastas. --label-ids filtra ainda mais, já que uma conversa tem de ter a pasta e cada id que passar. --date-from e --date-to leem a mensagem mais recente de cada conversa, e ambos os extremos são incluídos.
• —threads get inclui entre as mensagens as respostas em rascunho por enviar, marcadas com isDraft: true, e também abre um id de rascunho.
• —threads update precisa de --read, --no-read ou de uma etiqueta a acrescentar ou retirar. As remoções são aplicadas antes das adições. Um id de etiqueta que não corresponde a nenhuma etiqueta é recusado com label_not_found e nada muda na conversa, por isso crie primeiro a etiqueta. TRASH, SNOOZED e DRAFT são recusados com label_not_directly_settable: use threads trash e threads snooze.
• —threads trash não elimina nada, e a conversa continua legível com threads get, mas nenhum comando tira uma conversa do Lixo. Mover para o Lixo uma conversa adiada cancela também a sua reativação.
• —threads snooze envia <wake-at> tal como está, por isso indique um instante ISO 8601 futuro com Z ou um desvio, porque uma hora sem nenhum dos dois é lida no fuso horário do servidor. Um atraso como 3h é recusado por ser inválido. openemail snooze --until 3h aceita um atraso. As conversas são reativadas numa varredura de hora a hora, até cerca de uma hora mais tarde, e sempre na caixa de entrada.
• —threads list-attachments devolve cada ficheiro inteiro numa só resposta. Tire o id da mensagem dos messages de threads get. content é uma cadeia vazia quando os bytes guardados não são encontrados, por isso verifique o comprimento antes de o descodificar.

Mensagens por enviar guardadas na caixa de correio. Um id de rascunho começa por draft-.

• —drafts list --query pesquisa no assunto, no remetente e no início do corpo, e nunca sai dos rascunhos. older_than:30d e os outros operadores de data leem quando o rascunho foi guardado pela última vez, e to:, cc: e bcc: não correspondem a nada num rascunho.
• —Um rascunho é guardado como uma conversa com a etiqueta DRAFT, por isso threads get abre um e openemail inbox draft lista-os. drafts get, update e delete recusam um id de conversa normal com um 404.
• —Um openemail drafts create sem mais nada guarda um rascunho em branco. Só os comprimentos são verificados: um assunto até 998 caracteres, e --html e --text até 1,000,000 cada um, e --html é mantido quando os dois estão definidos. Não há opção para anexos.
• —drafts update substitui cada campo que enviar. Uma lista substitui por inteiro a guardada, por isso --to com um só endereço retira os outros, e uma atualização esvazia a lista de anexos do rascunho.
• —--thread-id regista a conversa a que um rascunho responde, mas o rascunho continua a ser guardado como uma conversa própria.
• —Voltar a executar drafts create guarda um segundo rascunho, porque não aceita chave de idempotência. Um nome a apresentar com uma vírgula divide-se em dois destinatários inválidos, por isso não use a vírgula.
• —openemail send --draft <id> --to <address> envia um rascunho. O corpo vem do rascunho, e o assunto também, a menos que passe --subject, enquanto os destinatários são os que indicar. Não pode ser combinado com um corpo, --template ou --translate.

As etiquetas que uma conversa pode ter. Um id de etiqueta de utilizador é USER_ seguido do nome com que foi criada, em maiúsculas, com cada sequência de espaços transformada em _, por isso Big Clients é USER_BIG_CLIENTS.

• —Um id nunca muda, nem depois de mudar o nome, por isso guarde ids em vez de nomes.
• —As etiquetas do sistema como INBOX, STARRED e UNREAD não são listadas e não podem ser alteradas nem eliminadas, embora threads update as aceite. labels get numa delas dá 404.
• —Um espaço de trabalho tem até 50 etiquetas de utilizador. Um nome que outra etiqueta já tem, comparado sem distinguir maiúsculas, é recusado com label_name_taken.
• —Uma cor é um valor hexadecimal como #3B82F6 ou um token de gradiente como gradient:sunset. --label-color aceita a cor inteira como JSON, e --label-color null limpa-a.
• —Uma etiqueta pertence ao espaço de trabalho, por isso mudar-lhe o nome, a cor ou eliminá-la altera-a para todos os que lá estão.
• —labels delete não pode ser anulado. Criar de novo uma etiqueta com o mesmo nome dá o mesmo id, mas as conversas não a recuperam. O seu threadCount em labels get diz quantas conversas a vão perder.

• —Um comando de correio aceita vários ids de conversa e informa sobre cada um, e com --json mostra { results, succeeded, failed }. Um comando desta página aceita um só id e mostra o que a API devolve.
• —openemail inbox lê cada conversa que lista para mostrar quem escreveu por último e o assunto. threads list faz um pedido por página e mostra só ids, que é tudo o que um pipeline precisa.
• —openemail read transforma uma mensagem HTML em texto e marca a conversa como lida. threads get mostra a conversa tal como a API a devolve e não altera nada.

Marque uma conversa como lida, arquive-a e etiquete-a num só pedido, onde mark read, archive e label add fariam três:

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

Crie uma etiqueta e arquive nela cada conversa correspondente. Encaminhado, --all mostra um objeto JSON por linha:

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

Guarde um ficheiro de uma mensagem. Os ids das mensagens estão nos 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

Escreva um rascunho, altere-o, leia-o de novo e depois envie-o:

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]

Limpe os rascunhos que ninguém guardou há 30 dias. A simulação mostra cada DELETE sem o enviar, e --yes responde à confirmação:

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

Escolha um gradiente da paleta, pré-visualize a alteração, faça-a e, mais tarde, retire de novo a cor:

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

Um scope em falta para com o código de saída 4. Nenhum destes comandos pede um código de verificação, nem com um início de sessão no navegador nem com uma chave de API.

Um início de sessão ou uma chave limitados a alguns endereços só veem as conversas entregues a esses endereços, e qualquer outra conversa dá 404, como se não existisse. As etiquetas pertencem ao espaço de trabalho, por isso continuam a ver-se todas, mas threadCount conta só as conversas que é possível ver.

• —threads list, drafts list e labels list leem uma página, de 25 a menos que --limit indique outra coisa, até 100. --cursor continua a partir do cursor que uma página mostrou. Um cursor de conversas mantém a ordem em que foi entregue, por isso envie com ele os mesmos filtros.
• —--all lê todas as páginas e --max <n> para depois desse número. Encaminhado ou com --ndjson mostra um objeto JSON por linha, e com --json um único documento { items, hasMore, nextCursor }.
• —hasMore pode ser true naquela que acaba por ser a última página, e a chamada seguinte não devolve então nenhum item. Uma conversa que recebe correio novo enquanto pagina passa à frente do cursor e não é devolvida pelas páginas seguintes, e o mesmo acontece com um rascunho guardado enquanto pagina.
• —threads trash, drafts delete e labels delete pedem-lhe confirmação. Sem supervisão, com --json, --no-input ou sem terminal, param com o código de saída 2 e não alteram nada, a menos que passe --yes.
• —--dry-run mostra o pedido que um comando enviaria, com a credencial ocultada, e sai com o código 0 sem o enviar nem pedir confirmação. Com --json mostra { dryRun, request }.

--data recebe o corpo inteiro como JSON, em linha, de um ficheiro com @path ou de stdin com -, e uma opção que também passe substitui a respetiva chave.

Um valor de opção vazio é um erro de utilização, por isso um campo que um valor vazio limpa passa por --data. --label-color null limpa a cor de uma 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"

O primeiro guarda o rascunho sem remetente, o segundo separa-o da conversa a que respondia e o terceiro limpa os destinatários.

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

openemail <namespace> <verb> --help mostra cada argumento e opção com o tipo, os scopes de que a chamada precisa, o método e o caminho, o que devolve e as notas da referência da API. Acrescente --json para ter a mesma ajuda como dados.