List files
Every file the mailbox holds: attachments sent and received, and uploads.
Runs the real call on your workspace.
GET /files
Every file the mailbox holds: attachments sent and received, and uploads.
Example
Needs files:read. q searches the name and the type, kind keeps image, pdf, audio, video or text, direction keeps inbound, outbound or uploaded, address keeps the files of one address, and sort is newest, oldest, largest or name. since and until take an ISO 8601 date or date-time and bound when the file was added: since includes that moment and until stops before it.
curl "$OE/files?kind=pdf&[email protected]&since=2026-09-01&sort=largest" -H "$AUTH"{ "object": "list", "data": [{ "object": "file", "id": "file_6bb640f5b99e47deb758f1f5", "filename": "invoice-0912.pdf", "mimeType": "application/pdf", "sizeBytes": 184233, "direction": "inbound", "threadId": "thread_2f9b…", "messageId": "<CAF7x…@mail.gmail.com>", "deliveredTo": "[email protected]", "usage": "received", "deletable": false, "createdAt": "2026-09-12T08:41:03.000Z" }], "hasMore": false, "nextCursor": null}A key limited to particular addresses or domains sees only the files that arrived at them, the same boundary the thread list uses. A deleted file is not listed.
address is compared with deliveredTo without regard to case, so it never widens what a narrowed key reaches: an address outside it returns an empty list.
Keys, roles and app grants that held threads:read or threads:write before files had scopes of their own were given the matching files:read or files:write. Reading an email with threads:read still reads the attachments on it.
The index starts from the day it shipped. Older attachments are still on their messages, where GET /threads/{id}/messages/{messageId}/attachments reads them.
A cursor carries on in the order it was handed out in, and one handed out under another sort is a 400 invalid_cursor.
direction is inbound, outbound or uploaded. deletable says whether DELETE /files/{id} would take the file, and usage says why not: received and sent stay with their message, linked went out as a download link that still works, and scheduled is attached to a message that has not gone out yet. usage is null exactly when deletable is true.
Google Workspace
Fastmail