Ficheiros
`files->list`, `listAll`, `iterate`, `get`, `download`, `listLinks`, `listAllLinks`, `iterateLinks`, `createLink`, `revokeLink`, `revokeAllLinks`, `stats`, `upload`, `delete` e `deleteMany`.
Todos os métodos
use OpenEmail\Constants\FileKinds;use OpenEmail\Constants\FileSorts; $largest = $client->files->list(kind: FileKinds::PDF, sort: FileSorts::LARGEST, limit: 1); foreach ($largest as $file) { foreach ($client->files->listAllLinks($file['id']) as $link) { echo $link['url'], ' ', $link['downloads'], PHP_EOL; } file_put_contents(basename($file['filename']), $client->files->download($file['id']));} $stats = $client->files->stats();echo $stats['totals']['files'], ' ', $stats['uploaded']['bytes'], PHP_EOL;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, que file_put_contents 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, listAll 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 DateTimeInterface ou uma string ISO 8601. since: inclui o seu momento e until: para antes dele. Um DateTimeInterface é enviado em UTC, e uma string com uma data simples como 2026-09-01 é lida 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\Constants\FileKinds, FileSorts e FileDirections nomeiam as opções. list devolve uma OpenEmail\Result\Page, e listAll devolve todos os ficheiros num único array. iterate devolve um Generator que entrega um ficheiro de cada vez e só obtém a página seguinte quando o ciclo precisa dela.
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, lançado como um PermissionException cujo isScopeMissing() é 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. Passe o nome por basename() antes de o escrever, como faz o exemplo, porque veio de quem enviou o ficheiro.
Ligações públicas
use OpenEmail\Constants\FileDirections; $uploads = $client->files->listAll(direction: FileDirections::UPLOADED, since: new \DateTimeImmutable('2026-09-01T00:00:00Z'));$file = $uploads[0] ?? null; if ($file !== null) { $link = $client->files->createLink($file['id'], domain: 'acme.com'); echo $link['url'], PHP_EOL; $client->files->revokeLink($file['id'], $link['id']);}createLink 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 ValidationException.
Cada createLink cria uma nova ligação, por isso nunca é repetido depois de uma resposta perdida: procure primeiro a ligação com listLinks. revokeLink 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 o cliente repete-o como uma leitura. Uma ligação desconhecida dá um 404, lançado como NotFoundException. revokeAllLinks desativa de uma vez todas as ligações de um ficheiro e indica quantas em revoked.
Carregar e eliminar
$report = "month,sent\n2026-09,1200\n";$upload = $client->files->upload($report, filename: 'report.csv', contentType: 'text/csv'); if ($upload['deletable']) { $client->files->delete($upload['id']);} $logo = $client->files->upload(new \SplFileInfo('logo.svg'));echo $logo['filename'], ' ', $logo['mimeType'], PHP_EOL; $result = $client->files->deleteMany(['file_0c4e7a91d2b84f63a5e19b7d', 'file_6bb640f5b99e47deb758f1f5']); foreach ($result['kept'] as $kept) { echo $kept['filename'], ' ', $kept['reason'], PHP_EOL;}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 contentType:, ou dados que levem o seu próprio tipo, e tudo o resto é guardado como application/octet-stream. O tipo nunca é deduzido de filename:, por isso uma string de bytes precisa de contentType: para ser guardada como outra coisa. Nunca é repetido, porque uma segunda tentativa guardaria uma segunda cópia.
Os dados são uma string de bytes, um SplFileInfo, um stream de fopen(), ou um stream ou ficheiro carregado PSR-7. Um SplFileInfo ou um stream aberto sobre um ficheiro não precisa de nenhum dos dois argumentos: o nome é o do próprio ficheiro, e o tipo vem da extensão quando o pacote a conhece, como .pdf ou .png. Um upload do Laravel ou do Symfony, e um ficheiro carregado PSR-7, trazem o nome e o tipo que o navegador enviou. Uma string não tem nome, por isso uma string sem filename: lança um InvalidArgumentException 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 ConflictException. deleteMany 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 deleteMany indica esses ficheiros em missing.