---
title: "nextmail files"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://nextmail.sh/docs/cli/reference/files"
area: "CLI"
category: "Reference"
---

# nextmail files

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `nextmail files list`

List one page of the files the mailbox holds

```bash
nextmail files list [flags]
```

Resolves one page of the Files page: every attachment the mailbox holds, sent and received, and every file uploaded to it, with its name, type, size, the address it came to, the thread it belongs to and whether it can be deleted.

Only an upload that nothing depends on can be deleted, and its `deletable` is true. Every other row has a `usage` saying what keeps it: `received`, `sent`, `linked` for an upload that went out as a download link that still works, or `scheduled` for one attached to a message that has not gone out yet.

A key limited to particular addresses or domains sees only the files that arrived at them, the same boundary the thread list uses, so it does not see files uploaded for the whole workspace. A deleted file is not listed.

The index starts from the day it shipped, so an older mailbox lists what has arrived since. Older attachments are still on their messages, where `threads.listAttachments` reads them.

Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max <n>` stops after that many items.

- Scopes: `files:read`.
- Needs a sign-in.
- Aliases: `ls`.

**Flags**

- `--q <value>`: Searches the file name and its type. Words match loosely, and a close spelling is tried when nothing matches exactly.
- `--kind <value>`: Keeps one kind: `image`, `pdf`, `audio`, `video` or `text`, the choices of the filter on the Files page.
- `--direction <value>`: Keeps one direction: `inbound` for files that arrived on a message, `outbound` for files that went out on one, `uploaded` for files put on the Files page.
- `--address <value>`: Keeps the files of one address, the `deliveredTo` of the file, compared without regard to case.
- `--since <when>`: Keeps files added at or after this moment. A `Date` or an ISO 8601 string.
- `--until <when>`: Keeps files added before this moment. A `Date` or an ISO 8601 string.
- `--sort <value>` (default `"newest"`): `newest` (the default), `oldest`, `largest` or `name`. A cursor carries on in the order it was handed out in.
- `--limit <n>` (default `25`): Page size, from 1 to 100. The server defaults to 25.
- `--cursor <value>`: The `nextCursor` of the previous page. Leave it out for the first page.
- `--all`: Fetch every page and stream the items as they arrive.
- `--max <n>`: Stop after this many items. Implies `--all`.
- `--ndjson`: Print every item as one JSON object per line. Implies `--all`

**Examples**

```bash
nextmail files list
```

With optional flags

```bash
nextmail files list --kind pdf --sort largest
```

Walk every page and stop after 100 items

```bash
nextmail files list --all --max 100
```

One JSON object per line when piped

```bash
nextmail files list --all > files.ndjson
```

Also available in: API [`GET /files`](https://nextmail.sh/docs/api/reference/files#get-files); TypeScript [`nextmail.files.list()`](https://nextmail.sh/docs/sdk/reference/files#list); Python [`files.list()`](https://nextmail.sh/docs/python/reference/files#list); Ruby [`files.list`](https://nextmail.sh/docs/ruby/reference/files#list); PHP [`files->list`](https://nextmail.sh/docs/php/reference/files#list); Go [`Files.List`](https://nextmail.sh/docs/go/reference/files#list); Java [`files().list`](https://nextmail.sh/docs/java/reference/files#list); C# [`Files.ListAsync`](https://nextmail.sh/docs/csharp/reference/files#list).

### `nextmail files get`

Read one file by id

```bash
nextmail files get <id> [flags]
```

Resolves one file: its name, type, size, whether it was sent, received or uploaded, the address it came to, the thread and message it belongs to, and whether it can be deleted. `download` fetches its bytes.

`deletable` is true only for an upload that nothing depends on. Otherwise `usage` says what keeps it: `received` or `sent` for a file that came in or went out on a message, `linked` for an upload that went out as a download link that still works, and `scheduled` for one attached to a message that has not gone out yet.

- Scopes: `files:read`.
- Needs a sign-in.
- Aliases: `show`, `view`.

**Arguments**

- `<id>` (required): The id from `list`, `file_` and 24 hex.

**Examples**

```bash
nextmail files get file_6bb640f5b99e47deb758f1f5
```

Print the raw JSON

```bash
nextmail files get file_6bb640f5b99e47deb758f1f5 --json
```

Also available in: API [`GET /files/{id}`](https://nextmail.sh/docs/api/reference/files#get-files-id); TypeScript [`nextmail.files.get()`](https://nextmail.sh/docs/sdk/reference/files#get); Python [`files.get()`](https://nextmail.sh/docs/python/reference/files#get); Ruby [`files.get`](https://nextmail.sh/docs/ruby/reference/files#get); PHP [`files->get`](https://nextmail.sh/docs/php/reference/files#get); Go [`Files.Get`](https://nextmail.sh/docs/go/reference/files#get); Java [`files().get`](https://nextmail.sh/docs/java/reference/files#get); C# [`Files.GetAsync`](https://nextmail.sh/docs/csharp/reference/files#get).

### `nextmail files stats`

Count the files and the space they take

```bash
nextmail files stats [flags]
```

Returns the numbers on the Analytics tab of the Files page in one request: how many files the mailbox holds and how many bytes they take, in all and split into received, sent and uploaded, the file types and the addresses taking the most space, how many files arrived on each of the last 30 days, and the download links still working with how often they were fetched. `uploadStorage` holds the space the uploads of the whole workspace take, beside what its plan allows.

Deleted files are not counted. A key limited to particular addresses or domains counts only the files that arrived at them, so files uploaded for the whole workspace are left out of its numbers.

- Scopes: `files:read`.
- Needs a sign-in.

**Examples**

```bash
nextmail files stats
```

Print the raw JSON

```bash
nextmail files stats --json
```

Also available in: API [`GET /files/stats`](https://nextmail.sh/docs/api/reference/files#get-files-stats); TypeScript [`nextmail.files.stats()`](https://nextmail.sh/docs/sdk/reference/files#stats); Python [`files.stats()`](https://nextmail.sh/docs/python/reference/files#stats); Ruby [`files.stats`](https://nextmail.sh/docs/ruby/reference/files#stats); PHP [`files->stats`](https://nextmail.sh/docs/php/reference/files#stats); Go [`Files.Stats`](https://nextmail.sh/docs/go/reference/files#stats); Java [`files().stats`](https://nextmail.sh/docs/java/reference/files#stats); C# [`Files.StatsAsync`](https://nextmail.sh/docs/csharp/reference/files#stats).

### `nextmail files download`

Fetch the bytes of a file

```bash
nextmail files download <id> [flags]
```

Resolves with the file exactly as it is stored, the same bytes the Download action on the Files page saves. The response carries the file's own `Content-Type` and name.

- Scopes: `files:read`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): The id from `list`.

**Flags**

- `-o, --out <file>`: Write the file here. Required on a terminal. Without it, piped output gets the raw bytes

**Examples**

```bash
nextmail files download file_6bb640f5b99e47deb758f1f5
```

Save the file

```bash
nextmail files download file_6bb640f5b99e47deb758f1f5 --out report.pdf
```

Also available in: API [`GET /files/{id}/content`](https://nextmail.sh/docs/api/reference/files#get-files-id-content); TypeScript [`nextmail.files.download()`](https://nextmail.sh/docs/sdk/reference/files#download); Python [`files.download()`](https://nextmail.sh/docs/python/reference/files#download); Ruby [`files.download`](https://nextmail.sh/docs/ruby/reference/files#download); PHP [`files->download`](https://nextmail.sh/docs/php/reference/files#download); Go [`Files.Download`](https://nextmail.sh/docs/go/reference/files#download); Java [`files().download`](https://nextmail.sh/docs/java/reference/files#download); C# [`Files.DownloadAsync`](https://nextmail.sh/docs/csharp/reference/files#download).

### `nextmail files list-links`

List the download links a file went out as

```bash
nextmail files list-links <id> [flags]
```

Resolves one page of the download links made for this file, newest first. A large attachment sent from Nextmail travels as a link rather than inside the message, and each send makes a link of its own. Every row says how often it was fetched, when last, and whether it was revoked. While one of its links still works, an upload cannot be deleted.

A file attached inside a message has no links, because nothing records when those are opened.

Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max <n>` stops after that many items.

- Scopes: `files:read`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): The file id from `list`.

**Flags**

- `--limit <n>` (default `25`): Page size, from 1 to 100. The server defaults to 25.
- `--cursor <value>`: The `nextCursor` of the previous page. Leave it out for the first page.
- `--all`: Fetch every page and stream the items as they arrive.
- `--max <n>`: Stop after this many items. Implies `--all`.
- `--ndjson`: Print every item as one JSON object per line. Implies `--all`

**Examples**

```bash
nextmail files list-links file_6bb640f5b99e47deb758f1f5
```

Walk every page and stop after 100 items

```bash
nextmail files list-links file_6bb640f5b99e47deb758f1f5 --all --max 100
```

One JSON object per line when piped

```bash
nextmail files list-links file_6bb640f5b99e47deb758f1f5 --all > files.ndjson
```

Also available in: API [`GET /files/{id}/links`](https://nextmail.sh/docs/api/reference/files#get-files-id-links); TypeScript [`nextmail.files.listLinks()`](https://nextmail.sh/docs/sdk/reference/files#listLinks); Python [`files.list_links()`](https://nextmail.sh/docs/python/reference/files#listLinks); Ruby [`files.list_links`](https://nextmail.sh/docs/ruby/reference/files#listLinks); PHP [`files->listLinks`](https://nextmail.sh/docs/php/reference/files#listLinks); Go [`Files.ListLinks`](https://nextmail.sh/docs/go/reference/files#listLinks); Java [`files().listLinks`](https://nextmail.sh/docs/java/reference/files#listLinks); C# [`Files.ListLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#listLinks).

### `nextmail files create-link`

Publish a file at a public link

```bash
nextmail files create-link <id> [flags]
```

Makes a public download link for the file and resolves with it. Anybody holding `url` can open the file without signing in, which is how an image or a document is referenced from an email or a web page. Each call makes a new link with its own download count, and a link keeps working until it is revoked with `revokeLink` or the file is deleted.

The link lives on the files host of `--domain` when that domain has one set up, such as `files.acme.com`, else on the files host of the address the file belongs to, else on the Nextmail API address. A file that came in or went out on a message is copied to public storage first. Programs and scripts are refused with 422 `file_unshareable`.

- Scopes: `files:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): The file id from `list`.

**Flags**

- `--domain <value>`: The domain whose files host serves the link, such as `acme.com`.

**Examples**

The required values only

```bash
nextmail files create-link file_6bb640f5b99e47deb758f1f5
```

With optional flags

```bash
nextmail files create-link file_6bb640f5b99e47deb758f1f5 --domain acme.com
```

Also available in: API [`POST /files/{id}/links`](https://nextmail.sh/docs/api/reference/files#post-files-id-links); TypeScript [`nextmail.files.createLink()`](https://nextmail.sh/docs/sdk/reference/files#createLink); Python [`files.create_link()`](https://nextmail.sh/docs/python/reference/files#createLink); Ruby [`files.create_link`](https://nextmail.sh/docs/ruby/reference/files#createLink); PHP [`files->createLink`](https://nextmail.sh/docs/php/reference/files#createLink); Go [`Files.CreateLink`](https://nextmail.sh/docs/go/reference/files#createLink); Java [`files().createLink`](https://nextmail.sh/docs/java/reference/files#createLink); C# [`Files.CreateLinkAsync`](https://nextmail.sh/docs/csharp/reference/files#createLink).

### `nextmail files revoke-link`

Revoke a public link

```bash
nextmail files revoke-link <id> <link-id> [flags]
```

Stops a public link from working, for good, including in mail that already went out with it, and resolves with the link, `revokedAt` set. Revoking a link that is already revoked resolves with it unchanged, so the call is safe to repeat. An unknown link is a 404.

- Scopes: `files:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): The file id from `list`.
- `<link-id>` (required): The link id from `listLinks` or `createLink`.

**Examples**

```bash
nextmail files revoke-link file_6bb640f5b99e47deb758f1f5 shr_2f9c4a1e7b3d
```

Skip the confirmation, for scripts

```bash
nextmail files revoke-link file_6bb640f5b99e47deb758f1f5 shr_2f9c4a1e7b3d --yes
```

Also available in: API [`DELETE /files/{id}/links/{linkId}`](https://nextmail.sh/docs/api/reference/files#delete-files-id-links-linkid); TypeScript [`nextmail.files.revokeLink()`](https://nextmail.sh/docs/sdk/reference/files#revokeLink); Python [`files.revoke_link()`](https://nextmail.sh/docs/python/reference/files#revokeLink); Ruby [`files.revoke_link`](https://nextmail.sh/docs/ruby/reference/files#revokeLink); PHP [`files->revokeLink`](https://nextmail.sh/docs/php/reference/files#revokeLink); Go [`Files.RevokeLink`](https://nextmail.sh/docs/go/reference/files#revokeLink); Java [`files().revokeLink`](https://nextmail.sh/docs/java/reference/files#revokeLink); C# [`Files.RevokeLinkAsync`](https://nextmail.sh/docs/csharp/reference/files#revokeLink).

### `nextmail files revoke-all-links`

Revoke every link to a file

```bash
nextmail files revoke-all-links <id> [flags]
```

Makes the file private, as Make private on the Files page does: every public download link to it stops working at once, including the ones in mail that already went out. Resolves with `revoked`, how many links were still working. The file itself stays, and `createLink` can publish it again at a new link.

A key limited to particular addresses reaches only the files that arrived at them, and any other file is a 404.

- Scopes: `files:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): The file id from `list`.

**Examples**

```bash
nextmail files revoke-all-links file_6bb640f5b99e47deb758f1f5
```

Skip the confirmation, for scripts

```bash
nextmail files revoke-all-links file_6bb640f5b99e47deb758f1f5 --yes
```

Also available in: API [`DELETE /files/{id}/links`](https://nextmail.sh/docs/api/reference/files#delete-files-id-links); TypeScript [`nextmail.files.revokeAllLinks()`](https://nextmail.sh/docs/sdk/reference/files#revokeAllLinks); Python [`files.revoke_all_links()`](https://nextmail.sh/docs/python/reference/files#revokeAllLinks); Ruby [`files.revoke_all_links`](https://nextmail.sh/docs/ruby/reference/files#revokeAllLinks); PHP [`files->revokeAllLinks`](https://nextmail.sh/docs/php/reference/files#revokeAllLinks); Go [`Files.RevokeAllLinks`](https://nextmail.sh/docs/go/reference/files#revokeAllLinks); Java [`files().revokeAllLinks`](https://nextmail.sh/docs/java/reference/files#revokeAllLinks); C# [`Files.RevokeAllLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#revokeAllLinks).

### `nextmail files upload`

Upload a file to the Files page

```bash
nextmail files upload <data> [flags]
```

Stores the bytes as a new file, the way the Upload button on the Files page does, and resolves with it: `direction` is `uploaded`, `usage` is null and `deletable` is true. Attach it to a send as `{ fileId }` in `emails.send`, which is how a file larger than the inline cap goes out.

`data` is a `Blob`, an `ArrayBuffer` or a `Uint8Array`, sent as the request body. The name travels as the `filename` query parameter, and it is cleaned rather than refused: characters a file name cannot hold become `_`, and a name longer than 255 characters is cut, keeping its extension. The type is `--content-type`, or a `Blob`'s own type when that is left out, and `application/octet-stream` without either. A value that is not shaped like a MIME type is stored as `application/octet-stream` too.

A key limited to particular addresses or domains uploads to the first address it holds, which becomes `deliveredTo`. An unlimited key uploads for the whole workspace and `deliveredTo` is null, so a narrowed key never reaches that file afterwards.

- Scopes: `files:write`.
- Needs a sign-in.

**Arguments**

- `<data>` (required): The file: a `Blob`, `ArrayBuffer` or `Uint8Array`, not empty and at most 100 MB.

**Flags**

- `--filename <value>`: The name the file is stored and downloaded under, such as `report.pdf`. A missing or blank name throws before anything is sent.
- `--content-type <value>`: The MIME type, such as `application/pdf`. Left out, a `Blob`'s own type is used, else `application/octet-stream`.
- `--timeout-ms <n>`: How long the upload may take, in milliseconds. Left out, it is 10 minutes, or the client `--timeout-ms` when that is longer. `0` waits as long as it takes.

**Examples**

The required values only

```bash
nextmail files upload ./photo.jpg
```

With optional flags

```bash
nextmail files upload ./photo.jpg --filename report.pdf --content-type application/pdf
```

Also available in: API [`POST /files`](https://nextmail.sh/docs/api/reference/files#post-files); TypeScript [`nextmail.files.upload()`](https://nextmail.sh/docs/sdk/reference/files#upload); Python [`files.upload()`](https://nextmail.sh/docs/python/reference/files#upload); Ruby [`files.upload`](https://nextmail.sh/docs/ruby/reference/files#upload); PHP [`files->upload`](https://nextmail.sh/docs/php/reference/files#upload); Go [`Files.Upload`](https://nextmail.sh/docs/go/reference/files#upload); Java [`files().upload`](https://nextmail.sh/docs/java/reference/files#upload); C# [`Files.UploadAsync`](https://nextmail.sh/docs/csharp/reference/files#upload).

### `nextmail files delete`

Delete an uploaded file for good

```bash
nextmail files delete <id> [flags]
```

Removes an uploaded file: its bytes are deleted from storage and it leaves the Files page. The row stays, marked deleted, so the index knows the file existed. There is no undo.

Only an upload that nothing depends on can be deleted, the files whose `deletable` is true. A file that was received or sent stays with its message, and so does an upload that went out as a download link that still works or is attached to a message that has not gone out yet. Those are refused with 409 `file_in_use`, and the message names the file and says why. An upload that was sent inside a message can still be deleted, because the message keeps its own copy, which is listed as a separate `sent` file.

`deleteMany` deletes up to 100 in one call and reports the ones it kept instead of failing.

- Scopes: `files:write`.
- Needs a sign-in.
- Asks you to confirm.
- Aliases: `rm`, `del`, `remove`.

**Arguments**

- `<id>` (required): The id from `list`.

**Examples**

```bash
nextmail files delete file_6bb640f5b99e47deb758f1f5
```

Skip the confirmation, for scripts

```bash
nextmail files delete file_6bb640f5b99e47deb758f1f5 --yes
```

Also available in: API [`DELETE /files/{id}`](https://nextmail.sh/docs/api/reference/files#delete-files-id); TypeScript [`nextmail.files.delete()`](https://nextmail.sh/docs/sdk/reference/files#delete); Python [`files.delete()`](https://nextmail.sh/docs/python/reference/files#delete); Ruby [`files.delete`](https://nextmail.sh/docs/ruby/reference/files#delete); PHP [`files->delete`](https://nextmail.sh/docs/php/reference/files#delete); Go [`Files.Delete`](https://nextmail.sh/docs/go/reference/files#delete); Java [`files().delete`](https://nextmail.sh/docs/java/reference/files#delete); C# [`Files.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/files#delete).

### `nextmail files delete-many`

Delete up to 100 files in one call

```bash
nextmail files delete-many <ids...> [flags]
```

Deletes every file in `ids` that can be deleted, the way `delete` deletes one, and reports the rest instead of failing. It is what selecting several files on the Files page and pressing Delete does.

Only an uploaded file that nothing depends on can be deleted. A file that was received or sent stays with its message, and so does an upload that went out as a download link that still works or is attached to a message that has not gone out yet. Each of those comes back in `kept` with its `usage` and a `reason` in plain words. An id that is unknown, already deleted or outside the addresses a narrowed key holds comes back in `missing`. The rule is checked again at the moment of deleting, so a file that became used in between is kept.

There is no undo.

- Scopes: `files:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<ids...>` (required): 1 to 100 file ids from `list`. More than 100, or none, is a 422 on `ids`. A repeated id counts once.

**Examples**

```bash
nextmail files delete-many file_6bb640f5b99e47deb758f1f5
```

Skip the confirmation, for scripts

```bash
nextmail files delete-many file_6bb640f5b99e47deb758f1f5 --yes
```

Also available in: API [`POST /files/batch-delete`](https://nextmail.sh/docs/api/reference/files#post-files-batch-delete); TypeScript [`nextmail.files.deleteMany()`](https://nextmail.sh/docs/sdk/reference/files#deleteMany); Python [`files.delete_many()`](https://nextmail.sh/docs/python/reference/files#deleteMany); Ruby [`files.delete_many`](https://nextmail.sh/docs/ruby/reference/files#deleteMany); PHP [`files->deleteMany`](https://nextmail.sh/docs/php/reference/files#deleteMany); Go [`Files.DeleteMany`](https://nextmail.sh/docs/go/reference/files#deleteMany); Java [`files().deleteMany`](https://nextmail.sh/docs/java/reference/files#deleteMany); C# [`Files.DeleteManyAsync`](https://nextmail.sh/docs/csharp/reference/files#deleteMany).