Ficheiros
`files.list`, `list_all`, `iterate`, `get`, `download`, `list_links`, `list_all_links`, `iterate_links`, `create_link`, `revoke_link`, `stats`, `upload`, `delete` e `delete_many`.
Todos os métodos
page = client.files.list(kind: "pdf", sort: "largest")file = page.items.first links = client.files.list_all_links(file[:id])p links.map { |link| [link[:url], link[:downloads]] } stats = client.files.statsputs stats.dig(:totals, :files), stats.dig(:uploaded, :bytes) File.binwrite(file[:filename], client.files.download(file[:id]))Cada ficheiro que a caixa de correio guarda, anexos enviados e recebidos e os ficheiros carregados nela: a página Ficheiros da aplicação. download devolve os bytes como String binária, que File.binwrite guarda sem alterações. As ligações são as ligações de transferência com que um ficheiro saiu, com quantas vezes cada uma foi obtida, e stats é o separador Análises.
list, list_all e iterate aceitam q:, kind: e sort:, e também direction: (inbound, outbound ou uploaded), address:, os ficheiros de um endereço, comparado sem distinguir maiúsculas de minúsculas, e since: e until:, um Time, um DateTime ou uma String ISO 8601. since: inclui o seu momento e until: para antes dele. Uma Date do Ruby é enviada como data simples, que esta lista lê como meia-noite UTC.
q: pesquisa o nome do ficheiro e o seu tipo. kind: é image, pdf, audio, video ou text, e sort: é newest, a predefinição, oldest, largest ou name. OpenEmail::FILE_KINDS, OpenEmail::FILE_SORTS e OpenEmail::FILE_DIRECTIONS nomeiam as opções. list devolve uma OpenEmail::Page, e list_all devolve todos os ficheiros num único Array. iterate passa cada ficheiro a um bloco e só obtém a página seguinte quando o ciclo precisa dela. Sem bloco, devolve um Enumerator.
Ler precisa de files:read, e carregar, eliminar e publicar ou revogar ligações precisam de files:write, que inclui files:read. Uma chave criada antes de os ficheiros terem âmbitos próprios recebeu os correspondentes. Uma chave sem o âmbito é recusada com um 403 insufficient_scope, e scope_missing? no erro é true. Uma chave limitada a determinados endereços ou domínios só vê os ficheiros que lhes chegaram, por isso não vê os ficheiros carregados para todo o espaço de trabalho.
download mantém o ficheiro inteiro em memória, por isso obtenha os ficheiros muito grandes um de cada vez.
Ligações públicas
uploads = client.files.list_all(direction: "uploaded", since: Time.utc(2026, 9, 1))file = uploads.first link = client.files.create_link(file[:id], domain: "acme.com")puts link[:url] client.files.revoke_link(file[:id], link[:id])create_link publica um ficheiro numa ligação de transferência pública que abre sem início de sessão, e devolve a ligação. A ligação fica no anfitrião de ficheiros de domain: quando esse domínio tem um, como files.acme.com, senão no anfitrião de ficheiros do endereço a que o ficheiro pertence, senão no endereço da API. Um ficheiro que entrou ou saiu numa mensagem é primeiro copiado para o armazenamento público, e um programa ou um script é recusado com um 422 file_unshareable, lançado como OpenEmail::ValidationError.
Cada create_link cria uma nova ligação, por isso nunca é repetido depois de uma resposta perdida: procure primeiro a ligação com list_links. revoke_link desativa uma ligação para sempre, incluindo no correio que já saiu, e devolve-a com revokedAt preenchido. Revogar uma ligação duas vezes é seguro, por isso a gem repete-o como uma leitura. Uma ligação desconhecida dá um 404, lançado como OpenEmail::NotFoundError.
Carregar e eliminar
upload = client.files.upload(File.binread("report.pdf"), filename: "report.pdf", content_type: "application/pdf")client.files.delete(upload[:id]) if upload[:deletable] invoice = client.files.upload(Pathname("invoice.pdf"))puts invoice[:filename], invoice[:mimeType] result = client.files.delete_many(["file_0c4e7a91d2b84f63a5e19b7d", "file_6bb640f5b99e47deb758f1f5"])result[:kept].each { |kept| puts "#{kept[:filename]} #{kept[:reason]}" }upload guarda os bytes tal como estão, até 100 MB, com o nome indicado em filename:, e devolve o ficheiro. Um envio anexa-o como {fileId: upload[:id]} nos attachments de emails.send. Passe content_type:, ou bytes que levem o seu próprio tipo, e tudo o resto é guardado como application/octet-stream. Nunca é repetido, porque uma segunda tentativa guardaria uma segunda cópia.
Os bytes são uma String binária, um IO ou um Pathname. Um Pathname ou um File não precisa de nenhum dos dois argumentos nomeados: o nome é o do próprio ficheiro, e o tipo vem da extensão quando a gem a conhece, como .pdf ou .png. Um ficheiro carregado no Rails traz o seu próprio original_filename e content_type. Bytes simples não têm nome, por isso uma String ou um StringIO sem filename: lança ArgumentError antes de qualquer envio.
Um carregamento pode durar 600 segundos, ou o timeout do cliente quando este for maior, e timeout: define outro limite para uma única chamada. Um cliente construído com timeout: 0 espera o tempo que o carregamento demorar.
Só um ficheiro carregado de que nada depende pode ser eliminado, e deletable e usage em cada ficheiro dizem-no de antemão. delete recusa qualquer outro ficheiro com um 409 file_in_use, lançado como OpenEmail::ConflictError. delete_many aceita até 100 ids, elimina o que pode e indica o resto em kept, cada um com o seu motivo, e em missing. Nenhum dos dois é repetido. Um 404 num segundo delete depois de uma resposta perdida significa que o primeiro funcionou, e um segundo delete_many indica esses ficheiros em missing.