Ficheiros, importações e definições

Cinco espaços de nomes cobrem o que rodeia o correio em si. openemail files é a página Ficheiros: cada anexo enviado e recebido e cada ficheiro carregado, com os bytes e as ligações de transferência com que saiu. openemail imports traz uma caixa de correio antiga para um endereço, e openemail provider-imports traz uma conta do Resend. openemail calendar lê os eventos encontrados no correio, e openemail settings lê e altera as preferências da caixa de correio e a assinatura e o rastreio de cada endereço.

• —Um id diz o que designa: file_ para um ficheiro, imp_ para uma importação de caixa de correio, pimp_ para uma importação do Resend e cal_ para um evento de calendário, cada um seguido de 24 caracteres hexadecimais. Uma ligação de transferência tem o seu próprio id, de files list-links ou files create-link.
• —--address-id numa importação é o id de um endereço, de openemail domains list-addresses <id>, não o endereço em si.
• —Os espaços de nomes respondem também a file, import, provider-import ou providerImports, e setting. Os verbos aceitam os aliases habituais quando os têm: ls para list, show e view para get, new e add para create, edit para settings update, e rm, del e remove para files delete.
• —Nenhum destes comandos pede um código de verificação a um início de sessão no navegador. Os que alteram algo de vez pedem-lhe confirmação, e --yes responde por um script.
• —openemail <command> --help lista cada argumento e opção com o tipo, o scope de que a chamada precisa, o método e o caminho, e o que devolve. Acrescente --json para ter a mesma página como dados.

openemail files lê e gere cada ficheiro que a caixa de correio guarda: os anexos que chegaram, os anexos que saíram e os ficheiros carregados na página Ficheiros. openemail open files abre a mesma página na aplicação web.

• —files list filtra com --q (o nome e o tipo), --kind (image, pdf, audio, video ou text), --direction (inbound, outbound ou uploaded), --address, --since e --until, e ordena com --sort (newest, oldest, largest ou name). --since e --until aceitam uma data ou data e hora ISO 8601: --since inclui o seu momento e --until para antes dele.
• —Só é possível eliminar um ficheiro carregado de que nada depende, e deletable indica-o de antemão. usage diz o que retém qualquer outro ficheiro: received, sent, linked para um ficheiro carregado cuja ligação de transferência ainda funciona, ou scheduled para um anexado a uma mensagem que ainda não saiu. delete recusa-os com 409 file_in_use. delete-many elimina o que consegue, lista o resto em kept com um motivo para cada um, e lista os ids desconhecidos em missing.
• —upload lê o ficheiro no caminho que indicar e guarda-o com o nome desse ficheiro, com o tipo que a extensão implica. --filename e --content-type substituem-nos. A partir de stdin, - precisa de --filename, e sem --content-type o tipo é application/octet-stream. O carregamento espera até 10 minutos, o que --timeout-ms altera.
• —O id que upload devolve anexa o ficheiro a um envio como { "fileId": "…" } em openemail emails send --attachments, que é como sai um ficheiro acima do limite de 5 MB em linha.
• —Um ficheiro vazio dá 400 upload_empty, um programa ou script (avaliado pelo nome) dá 400 upload_dangerous, e um ficheiro com mais de 100 MB dá 413 upload_too_large. Um espaço de trabalho guarda até 10 GB de carregamentos e aceita 500 carregamentos por hora.
• —download precisa de --out <file> num terminal e sem ele para com o código de saída 2. Encaminhado, os bytes vão para stdout, e --out - também pede stdout. O ficheiro inteiro é mantido em memória.
• —create-link cria uma ligação nova em cada chamada, com a sua própria contagem de transferências, e a ligação funciona até ser revogada ou o ficheiro ser eliminado. Fica no domínio de ficheiros de --domain quando esse domínio tem um, como files.acme.com, senão no domínio de ficheiros do endereço do ficheiro, senão no endereço da API. Um programa ou script é recusado com 422 file_unshareable.
• —revoke-link pode ser repetido sem risco: uma ligação já revogada volta inalterada.
• —Uma chave ou um início de sessão limitados a determinados endereços ou domínios só veem os ficheiros que lhes chegaram, nunca os ficheiros carregados para todo o espaço de trabalho, e os seus próprios carregamentos pertencem ao primeiro endereço que têm.
• —O índice de ficheiros começa no dia em que foi lançado. Os anexos mais antigos continuam nas suas mensagens, onde openemail threads list-attachments <id> os lê.

openemail imports traz uma caixa de correio antiga para um endereço: arquivos do Google Takeout, ficheiros .mbox do Apple Mail, do Thunderbird e da maioria das aplicações de computador, ficheiros .eml, e arquivos .zip ou .tgz que contenham qualquer um deles, até 100 GB por ficheiro e 50 ficheiros por importação. As conversas, as datas e as etiquetas são mantidas. O correio importado é silencioso: não executa regras, reencaminhamentos, notificações, resumos nem webhooks.

import-files é o que quase toda a gente precisa: cria a importação, carrega cada ficheiro por partes com uma linha de progresso e inicia-a. Os outros verbos são esses passos um a um, para terminar um carregamento que parou ou para o conduzir você mesmo. create devolve o plano, chunkBytes e os chunks de cada ficheiro, upload-chunk envia uma parte, upload-state diz que partes chegaram, e start põe a importação em fila. openemail open imports mostra as mesmas importações na aplicação web.

• —O endereço tem de ser um dos domínios próprios do espaço de trabalho em nome do qual a chave ou o início de sessão possa agir. Só corre uma importação por endereço: outra enquanto uma está em fila ou em curso dá 409 already_running.
• —import-files aceita --files uma vez por ficheiro, ou vários caminhos separados por vírgulas, e envia cada um com o seu próprio nome de ficheiro. --options aceita JSON como {"keepInbox":false,"includeSpam":true}. Em create esses mesmos três são interruptores: --options-keep-inbox, --options-include-spam e --options-include-trash, cada um desligado com --no- à frente, como em --no-options-keep-inbox.
• —keepInbox está ligado por predefinição, por isso o correio da caixa de entrada antiga chega a Caixa de entrada com o estado de não lido. Desligado, arquiva tudo em Arquivo. O spam e o lixo ficam de fora, a menos que os inclua.
• —create aceita --files como JSON, em linha ou de um ficheiro com @path, e cada bytes tem de ser o tamanho exato do ficheiro que carregar depois.
• —Cada parte tem exatamente chunkBytes, exceto a última parte de um ficheiro, e uma parte com o comprimento errado dá 400 bad_chunk. start recusa um ficheiro com partes em falta com 412 missing_chunks, e um que não seja um arquivo nem uma caixa de correio com 400 unsupported_file. Numa importação que já saiu de uploading, devolve a importação inalterada.
• —Se uma parte continuar a falhar depois das novas tentativas, import-files para com a importação em uploading. O bloco abaixo envia as partes em falta do primeiro ficheiro e inicia-a.
• —Uma importação indica processedBytes de totalBytes, e counts com seen, imported, duplicate, filtered, failed e threads. lastError só é definido quando status é failed.
• —list-failures dá a cada falha um reason: too-large (mais de 50 MB), unparseable, no-date, storage-error, unreadable-entry, encrypted-entry ou archive-limit, com o assunto e o remetente quando foi possível lê-los.
• —cancel numa importação terminada dá 409 not_cancellable. delete-upload cancela uma importação que ainda está a ser carregada, e recusa uma que está em fila ou em curso com 409 still_running, por isso cancele-a primeiro.

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 traz um espaço de trabalho do Resend com uma chave de API do Resend com acesso total. As supressões mantêm o motivo, os segmentos tornam-se audiências, os contactos com subscrição chegam com os nomes, e os modelos chegam como modelos HTML com as variáveis declaradas. Os webhooks são registados desligados, porque aqui as entregas são assinadas de outra forma. Uma chave de assinatura ou um token não podem sair do Resend, por isso os domínios e as chaves de API voltam como uma lista de verificação no relatório.

• —Passe a chave do Resend como @path para a ler de um ficheiro, ou como - para a ler de stdin, para ficar fora do histórico da sua shell e da lista de processos. Uma chave escrita na linha de comandos continua a funcionar, com um aviso. --dry-run mostra o corpo com a chave ocultada.
• —--resources aceita qualquer um de suppressions, audiences, contacts, templates, webhooks, domains e api-keys, separados por vírgulas ou repetidos.
• —Uma chave só de envio dá 400 restricted_key. Crie no Resend uma chave com acesso total para a importação, e revogue-a depois.
• —inspect lê a primeira página de cada recurso e devolve counts, um { count, more } por recurso, com more definido quando um recurso vai além da primeira página.
• —Corre uma importação por espaço de trabalho de cada vez, e uma segunda dá 409 already_running. Executar a mesma importação duas vezes não duplica nada. A chave só é guardada cifrada enquanto a importação corre, e é apagada quando termina, falha ou é cancelada.
• —Os contactos que cancelaram a subscrição no Resend ficam de fora e são contados em report.contacts.unsubscribed.
• —report.domains lista cada domínio do Resend com um state: absent quando não está neste espaço de trabalho, added quando está mas não está verificado, e verified, com os registos que tinha no Resend. Acrescente um em falta com openemail domains create. report.apiKeys indica as chaves a criar de novo com openemail keys create.
• —Com um início de sessão no navegador só o proprietário do espaço de trabalho pode usar estes comandos, e um membro recebe 403 owner_only. Uma chave de API não está sujeita a isso. Uma chave ou um início de sessão limitados a determinados endereços ou domínios não podem inspecionar nem criar uma importação, já que as audiências, as supressões e os modelos pertencem a todo o espaço de trabalho.
• —create também precisa do scope de cada recurso que importa: audiences:write para as audiências, contacts:write e audiences:write para os contactos, templates:write para os modelos, webhooks:write para os webhooks e domains:read para os domínios.

openemail calendar lê os eventos de calendário encontrados no correio. Os três comandos só leem. list-events expande cada evento nas suas ocorrências dentro de um período que indicar, por isso uma reunião semanal é uma linha por semana, e get-event e get-event-ics leem um evento inteiro. openemail open calendar abre o calendário na aplicação web.

• —--from e --to são datas e horas ISO 8601 como 2026-10-01T00:00:00Z. --to tem de ser posterior a --from e no máximo 366 dias depois, já que uma série que se repete não tem um fim até ao qual listar. Um limite em falta dá 422 invalid_parameter. Um limite que não é possível interpretar, um período invertido ou demasiado longo, ou um fuso desconhecido dá 400 invalid_parameter.
• —--timezone é um fuso IANA como Europe/London, UTC se for omitido. Expande os eventos guardados sem fuso próprio, o que decide o dia em que calha um evento de dia inteiro.
• —get-event e get-event-ics aceitam o eventId de uma ocorrência, não o uid do iCalendar. Uma série que se repete é um só evento, por isso o seu start e o seu end descrevem a primeira instância.
• —Os eventos cancelados também são listados, com status em CANCELLED. myPartstat é a resposta registada para qualquer endereço que o espaço de trabalho tem nos seus próprios domínios, e null quando nenhum deles é participante.
• —A paginação continua com --cursor e o mesmo período. Uma chave ou um início de sessão limitados a determinados endereços só veem os eventos que um deles organiza ou em que participa, e qualquer outro evento dá 404.
• —get-event-ics declara METHOD:PUBLISH, por isso importá-lo mostra o evento tal como está em vez de oferecer aceitá-lo ou recusá-lo. Os eventos com hora são escritos como instantes UTC e os de dia inteiro como datas. DTSTAMP é a hora da transferência, por isso duas transferências de um evento inalterado diferem nessa linha.

openemail settings lê e altera as preferências da caixa de correio, como o fuso horário, o idioma, o formato de hora e as listas de bloqueio. Quatro definições pertencem a um endereço e não ao espaço de trabalho: signature, openEmailSignature (o rodapé do OpenEmail), trackOpens e trackClicks. Indique o endereço com --address, ou *@acme.com para o catch-all de um domínio.

• —Sem --address, get lê as quatro definições por endereço como os valores predefinidos incluídos: sem assinatura, o rodapé do OpenEmail ligado, e o rastreio de aberturas e de ligações ligado. Com ele, vêm dos valores próprios do endereço, depois do catch-all do seu domínio quando o catch-all apanhou esse endereço, e depois dos valores predefinidos. Um endereço com sinal de mais sem definições próprias lê as do seu endereço base.
• —Sem --address, update recusa --signature, --open-email-signature, --track-opens e --track-clicks com 422 address_required e não escreve nada. Com ele, update aceita só essas quatro, e qualquer outra coisa dá 422 not_per_address. O endereço tem de estar neste espaço de trabalho, ou ser *@domain para um domínio verificado aqui com o catch-all ligado.
• —Os interruptores desligam-se com --no- à frente: --no-open-email-signature, --no-track-opens e --no-track-clicks.
• —--signature é HTML com no máximo 150.000 caracteres, sanitizado ao ser escrito, por isso o que volta é o que será enviado. Uma cadeia vazia remove-a. Se um envio a acrescenta depende do envio: consulte --signature em openemail emails send --help.
• —As opções cobrem os campos habituais. --data aceita qualquer definição guardada como JSON, em linha, de um ficheiro com @path ou de stdin com -, como timeFormat, weekStart, undoSendEnabled, blockedSenders ou blockedDomains. As chaves que as definições não conhecem são descartadas sem erro, e uma chave conhecida com o tipo errado dá 422 invalid_parameter.
• —Uma lista como blockedDomains é substituída por inteiro, por isso leia-a primeiro e devolva-a com a sua alteração, como faz o exemplo abaixo. Uma entrada da lista de bloqueio demasiado curta para ser uma regra dá 422 blocklist_entry_too_broad.
• —--timezone e --language são guardados tal como são dados, sem verificação, por isso verifique um fuso ou um código de idioma antes de o enviar.
• —Os campos de privacidade, externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords e useDefaultBlockedWords, pertencem ao espaço de trabalho. Uma chave ou um início de sessão limitados a determinados endereços ou domínios não os podem alterar, e em --address só podem indicar um endereço que tenham, ou um catch-all de um domínio que tenham por inteiro. Qualquer uma das recusas dá 422 capability_unsupported.
• —Uma atualização sem nada não altera nada e devolve as definições atuais. defaultEmailAlias só pré-seleciona o endereço From no editor da aplicação web, e a API nunca o usa para escolher um remetente.

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

Cada create-link cria uma ligação nova, por isso execute-o uma vez e leia de novo a ligação com list-links. revoke-link para-a mais tarde, também no correio que já saiu.

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

Com --all num pipe, files list mostra um ficheiro por linha. xargs -n 100 passa a delete-many no máximo 100 ids por chamada, e qualquer ficheiro que tenha passado a ser usado entretanto volta em kept com o motivo em vez de fazer falhar a chamada.

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 em import-files mostra o POST /imports que enviaria, com o nome e o tamanho de cada ficheiro, e não carrega nada. list-failures lê 100 de cada vez: passe o nextCursor que mostrou como --after para a página seguinte.

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 -

A simulação mostra o PATCH /settings?address=sales%40acme.com e o seu corpo sem o enviar. A linha do catch-all define o rastreio para cada endereço que o catch-all de acme.com apanha, e a última linha acrescenta um domínio à lista de bloqueio sem retirar os outros.

• —Um início de sessão ou uma chave sem o scope para com o código de saída 4, indica o scope em falta e explica como o obter.
• —files revoke-link, files delete, files delete-many, imports cancel, imports delete-upload e provider-imports cancel pedem-lhe confirmação. Responder que não sai com o código 10 e não altera nada. Sem supervisão e sem --yes, param com o código de saída 2 antes de enviar o que quer que seja.
• —Nenhum comando desta página pede um código de verificação, nem com um início de sessão no navegador nem com uma chave de API, por isso --yes é tudo o que um script precisa.
• —--dry-run mostra o pedido que uma alteração enviaria, com o corpo, e sai com o código 0 sem o enviar nem lhe pedir confirmação. O corpo de um ficheiro é mostrado como o seu tamanho e tipo.
• —files list, files list-links, imports list, provider-imports list e calendar list-events leem uma página: --limit aceita de 1 a 100 e o servidor envia 25 quando é omitido, e --cursor aceita o nextCursor da página anterior. --all lê todas as páginas, --max <n> para depois desse número de itens, e --ndjson, ou --all num pipe, mostra um objeto JSON por linha. Com --json mostram um único documento { items, hasMore, nextCursor }.
• —imports list-failures pagina à sua maneira: --after aceita o nextCursor da página anterior, --limit é no máximo 100, o valor predefinido, e não há --all. Com --json mostra { object, data, nextCursor }.
• —As leituras e as alterações que têm o mesmo efeito duas vezes são repetidas depois de uma falha de rede: files revoke-link, imports upload-chunk, imports start e settings update. Qualquer outra alteração é enviada uma vez. Depois de perder uma resposta, verifique antes de tentar de novo: um segundo upload guarda uma segunda cópia e um segundo create-link cria uma segunda ligação, um 404 no seu segundo files delete significa que o primeiro funcionou, e um segundo delete-many lista em missing o que o primeiro eliminou.
• —Uma recusa sai com o código do seu estado: 4 para um 403, 5 para um 404, 6 para um 409, 7 para um 400 ou um 422, e 8 para um 429.