---
title: "List files"
description: "Every file the mailbox holds: attachments sent and received, and uploads."
url: "https://nextmail.sh/docs/api/files/list"
area: "API"
category: "Mailbox"
---

# List files

Every file the mailbox holds: attachments sent and received, and uploads.

`GET /files`

## 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**

```
curl "$OE/files?kind=pdf&address=billing@acme.com&since=2026-09-01&sort=largest" -H "$AUTH"
```

**Response**

```
{
  "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": "billing@acme.com",
      "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.

## Reference

- [`GET /files`](https://nextmail.sh/docs/api/reference/files#get-files): full reference