Файлы
`files.list`, `list_all`, `iterate`, `get`, `download`, `list_links`, `list_all_links`, `iterate_links`, `create_link`, `revoke_link`, `stats`, `upload`, `delete` и `delete_many`.
Все методы
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]))Все файлы, которые хранит почтовый ящик: отправленные и полученные вложения и загруженные в него файлы. Это страница «Файлы» в приложении. download возвращает байты как двоичную String, которую File.binwrite сохраняет без изменений. Ссылки являются ссылками для скачивания, с которыми файл уходил, вместе с тем, сколько раз каждая была запрошена, а stats соответствует вкладке «Аналитика».
list, list_all и iterate принимают q:, kind: и sort:, а также direction: (inbound, outbound или uploaded), address: (файлы одного адреса, сравнение без учёта регистра) и since: и until: в виде Time, DateTime или String ISO 8601. since: включает свой момент, а until: останавливается перед ним. Date из Ruby отправляется как голая дата, которую этот список читает как полночь UTC.
q: ищет по имени файла и его типу. kind: принимает image, pdf, audio, video или text, а sort: принимает newest (по умолчанию), oldest, largest или name. OpenEmail::FILE_KINDS, OpenEmail::FILE_SORTS и OpenEmail::FILE_DIRECTIONS перечисляют варианты. list возвращает одну OpenEmail::Page, а list_all возвращает все файлы одним Array. iterate передаёт каждый файл в блок и запрашивает следующую страницу, только когда она нужна циклу. Без блока он возвращает Enumerator.
Для чтения нужна files:read, а для загрузки, удаления и публикации или отзыва ссылок нужна files:write, которая включает files:read. Ключ, созданный до появления у файлов собственных областей, получил соответствующие. Ключ без нужной области отклоняется с 403 insufficient_scope, и у ошибки scope_missing? равно true. Ключ, ограниченный определёнными адресами или доменами, видит только файлы, пришедшие на них, поэтому не видит файлов, загруженных для всего рабочего пространства.
download держит весь файл в памяти, поэтому очень большие файлы скачивайте по одному.
Публичные ссылки
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 публикует файл по публичной ссылке для скачивания, которая открывается без входа, и возвращает ссылку. Ссылка размещается на хосте файлов domain:, если у этого домена он есть, например files.acme.com, иначе на хосте файлов адреса, которому принадлежит файл, иначе на адресе API. Файл, который пришёл или ушёл с сообщением, сначала копируется в публичное хранилище, а программа или скрипт отклоняются с 422 file_unshareable, выбрасываемым как OpenEmail::ValidationError.
Каждый create_link создаёт новую ссылку, поэтому он никогда не повторяется после потерянного ответа: сначала поищите ссылку через list_links. revoke_link навсегда отключает ссылку, в том числе в уже отправленных письмах, и возвращает её с заданным revokedAt. Повторный отзыв безопасен, поэтому гем повторяет его как чтение. Неизвестная ссылка даёт 404, выбрасываемый как OpenEmail::NotFoundError.
Загрузка и удаление
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 сохраняет байты как есть, до 100 МБ, под именем из filename: и возвращает файл. Отправка прикрепляет его как {fileId: upload[:id]} в attachments вызова emails.send. Передайте content_type: или байты, которые несут собственный тип, а всё остальное сохраняется как application/octet-stream. Вызов никогда не повторяется, потому что вторая попытка сохранила бы вторую копию.
Байты передаются как двоичная String, IO или Pathname. Pathname или File не нуждаются ни в одном из этих аргументов: имя берётся у самого файла, а тип выводится из расширения, если гем его знает, например .pdf или .png. Загрузка Rails приносит собственные original_filename и content_type. Простые байты не несут имени, поэтому String или StringIO без filename: выбрасывают ArgumentError ещё до отправки.
Загрузка может длиться 600 секунд или timeout клиента, если он больше, а timeout: задаёт другой предел для одного вызова. Клиент, собранный с timeout: 0, ждёт столько, сколько длится загрузка.
Удалить можно только загрузку, от которой ничего не зависит, и об этом заранее говорят deletable и usage каждого файла. delete отклоняет любой другой файл с 409 file_in_use, выбрасываемым как OpenEmail::ConflictError. delete_many принимает до 100 идентификаторов, удаляет что может, а остальные сообщает в kept, каждый с причиной, и в missing. Ни один из них не повторяется. 404 на втором delete после потерянного ответа означает, что первый сработал, а второй delete_many сообщает такие файлы в missing.