--- title: "Files" description: "Every file the mailbox holds." url: "https://nextmail.sh/docs/mcp/tools/files" area: "MCP server" category: "Tools" --- # Files Every file the mailbox holds. ## Files tools | Tool | What it does | | --- | --- | | listFiles | Every file the mailbox holds, attachments sent and received and the files uploaded to it, searchable by name, filtered by kind, direction, address and the dates it was added, and sorted newest, oldest, largest or by name. Each one says whether it can be deleted. Returned a page at a time. | | getFile | One file, whether it can be deleted and why not, with every download link it went out as and how often each was fetched. | | getFileStats | The numbers on the Analytics tab of the Files page: files and space in all, split into received, sent and uploaded, the largest types, the addresses holding the most, the live download links and what was added each day of the last 30. | | uploadFile | Upload a file the way the Upload button does, as base64 up to 5 MB. Its id can be attached to a send as `{ fileId }`. A chat asks first unless you asked for it. | | deleteFile | Delete an uploaded file that nothing depends on. Its bytes go for good. A chat always asks first. | | deleteFiles | Delete up to 100 uploaded files in one call. Each one in use is kept and named with the reason, and an id that is not found is listed. A chat always asks first. | | createFileLink | Publish a file at a public download link that opens with no sign-in, on the files host of the domain you name when it has one. Programs and scripts are refused. | | revokeFileLink | Stop a public download link from working, for good, including in mail that already went out with it. | | makeFilePrivate | Make a file private, as Make private on the Files page does: every public link to it stops working at once, in mail already sent too. A chat always asks first. | > Reading files needs `files:read`, and uploading, deleting and publishing or revoking links need `files:write`, which includes `files:read`. Reading an email with `threads:read` still reads the attachments on it. Somebody limited to some addresses sees only the files on those addresses, and uploads to the first one they can send from. > No tool returns the bytes. Downloading a file is `GET /files/{id}/content` on the REST API, `files.download` in the SDK or `nextmail files download` on the command line. > Only an upload that nothing depends on can be deleted. A received or sent file 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. An upload sent inside a message can go, because the sent message keeps its own copy. ## Reference ### `listFiles` Every file this mailbox holds, the Files page: attachments that were received or sent, and files somebody uploaded. Each line gives the name, type, size, which address it belongs to, the thread it came on, and whether it can be deleted. Only an uploaded file that no message depends on can be deleted; a received or sent file stays with its message. q searches the name and the type, kind keeps images, PDFs, audio, video or text, direction keeps received (inbound), sent (outbound) or uploaded files, address keeps the files of one address, since and until bound when the file was added (ISO dates), and sort is newest (the default), oldest, largest or name. Somebody limited to some addresses sees only the files that belong to them. One page at a time: when more follow, the last line gives a cursor to pass back for the next page. - Scopes: `files:read`. - The app's assistant runs it without asking. - Toolkit: `files`. **Inputs** - `q` (`string`, up to 200 characters) - `kind` (`string`, one of `"image"`, `"pdf"`, `"audio"`, `"video"`, `"text"`) - `direction` (`string`, one of `"inbound"`, `"outbound"`, `"uploaded"`) - `address` (`string`, 3 to 320 characters) - `since` (`string`, format `date-time`) - `until` (`string`, format `date-time`) - `sort` (`string`, one of `"newest"`, `"oldest"`, `"largest"`, `"name"`) - `limit` (`integer`, at least 1, at most 100) - `cursor` (`string`) 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), [`nextmail.files.listAll()`](https://nextmail.sh/docs/sdk/reference/files#listAll), [`nextmail.files.iterate()`](https://nextmail.sh/docs/sdk/reference/files#iterate); Python [`files.list()`](https://nextmail.sh/docs/python/reference/files#list), [`files.list_all()`](https://nextmail.sh/docs/python/reference/files#listAll), [`files.iterate()`](https://nextmail.sh/docs/python/reference/files#iterate); Ruby [`files.list`](https://nextmail.sh/docs/ruby/reference/files#list), [`files.list_all`](https://nextmail.sh/docs/ruby/reference/files#listAll), [`files.iterate`](https://nextmail.sh/docs/ruby/reference/files#iterate); PHP [`files->list`](https://nextmail.sh/docs/php/reference/files#list), [`files->listAll`](https://nextmail.sh/docs/php/reference/files#listAll), [`files->iterate`](https://nextmail.sh/docs/php/reference/files#iterate); Go [`Files.List`](https://nextmail.sh/docs/go/reference/files#list), [`Files.ListAll`](https://nextmail.sh/docs/go/reference/files#listAll), [`Files.Iterate`](https://nextmail.sh/docs/go/reference/files#iterate); Java [`files().list`](https://nextmail.sh/docs/java/reference/files#list), [`files().listAll`](https://nextmail.sh/docs/java/reference/files#listAll), [`files().iterate`](https://nextmail.sh/docs/java/reference/files#iterate); C# [`Files.ListAsync`](https://nextmail.sh/docs/csharp/reference/files#list), [`Files.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/files#listAll), [`Files.IterateAsync`](https://nextmail.sh/docs/csharp/reference/files#iterate). ### `getFile` One file from listFiles by its id, whether it can be deleted and why not, and every download link it went out as: how often each was fetched, when last, and whether it was revoked. A file attached inside a message has no links, because nothing records when those are opened. One page at a time: when more follow, the last line gives a cursor to pass back for the next page. - Scopes: `files:read`. - The app's assistant runs it without asking. - Toolkit: `files`. **Inputs** - `id` (`string`, required, 1 to 128 characters) - `limit` (`integer`, at least 1, at most 100) - `cursor` (`string`) Also available in: API [`GET /files/{id}`](https://nextmail.sh/docs/api/reference/files#get-files-id), [`GET /files/{id}/links`](https://nextmail.sh/docs/api/reference/files#get-files-id-links); TypeScript [`nextmail.files.get()`](https://nextmail.sh/docs/sdk/reference/files#get), [`nextmail.files.listLinks()`](https://nextmail.sh/docs/sdk/reference/files#listLinks), [`nextmail.files.listAllLinks()`](https://nextmail.sh/docs/sdk/reference/files#listAllLinks), [`nextmail.files.iterateLinks()`](https://nextmail.sh/docs/sdk/reference/files#iterateLinks); Python [`files.get()`](https://nextmail.sh/docs/python/reference/files#get), [`files.list_links()`](https://nextmail.sh/docs/python/reference/files#listLinks), [`files.list_all_links()`](https://nextmail.sh/docs/python/reference/files#listAllLinks), [`files.iterate_links()`](https://nextmail.sh/docs/python/reference/files#iterateLinks); Ruby [`files.get`](https://nextmail.sh/docs/ruby/reference/files#get), [`files.list_links`](https://nextmail.sh/docs/ruby/reference/files#listLinks), [`files.list_all_links`](https://nextmail.sh/docs/ruby/reference/files#listAllLinks), [`files.iterate_links`](https://nextmail.sh/docs/ruby/reference/files#iterateLinks); PHP [`files->get`](https://nextmail.sh/docs/php/reference/files#get), [`files->listLinks`](https://nextmail.sh/docs/php/reference/files#listLinks), [`files->listAllLinks`](https://nextmail.sh/docs/php/reference/files#listAllLinks), [`files->iterateLinks`](https://nextmail.sh/docs/php/reference/files#iterateLinks); Go [`Files.Get`](https://nextmail.sh/docs/go/reference/files#get), [`Files.ListLinks`](https://nextmail.sh/docs/go/reference/files#listLinks), [`Files.ListAllLinks`](https://nextmail.sh/docs/go/reference/files#listAllLinks), [`Files.IterateLinks`](https://nextmail.sh/docs/go/reference/files#iterateLinks); Java [`files().get`](https://nextmail.sh/docs/java/reference/files#get), [`files().listLinks`](https://nextmail.sh/docs/java/reference/files#listLinks), [`files().listAllLinks`](https://nextmail.sh/docs/java/reference/files#listAllLinks), [`files().iterateLinks`](https://nextmail.sh/docs/java/reference/files#iterateLinks); C# [`Files.GetAsync`](https://nextmail.sh/docs/csharp/reference/files#get), [`Files.ListLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#listLinks), [`Files.ListAllLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#listAllLinks), [`Files.IterateLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#iterateLinks). ### `getFileStats` The numbers on the Analytics tab of the Files page: how many files and how much space in all, split into received, sent and uploaded, the largest file types, the addresses holding the most, the download links still live with their downloads, and how many files were added each day of the last 30. Somebody limited to some addresses counts only the files that belong to them. - Scopes: `files:read`. - The app's assistant runs it without asking. - Toolkit: `files`. **Inputs** Takes no input. 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). ### `uploadFile` Upload a file to the Files page, the way the Upload button does. content is the file itself in base64, at most 5 MB once decoded; filename is the name it is stored under; contentType is its MIME type and defaults to application/octet-stream. Somebody limited to some addresses uploads to the first address they can send from; everybody else uploads to the whole workspace. The id it answers with can be attached to a send as { fileId }. Programs and scripts are refused, and uploads count against the workspace upload limits. - Scopes: `files:write`. - The app's assistant asks first unless you asked for it. - Toolkit: `files`. **Inputs** - `filename` (`string`, required, 1 to 255 characters) - `content` (`string`, required, 1 to 6990515 characters) - `contentType` (`string`, up to 255 characters) 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). ### `deleteFile` Delete an uploaded file for good: its bytes are removed from storage and it leaves the Files page. Nothing brings it back. Only an uploaded file that no message 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 or waits on a message that has not gone out yet; listFiles says which files can be deleted. - Scopes: `files:write`. - The app's assistant always asks first. - Toolkit: `files`. **Inputs** - `id` (`string`, required, 1 to 128 characters) 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). ### `deleteFiles` Delete up to 100 uploaded files in one call, the way deleteFile does one, as selecting several on the Files page and pressing Delete does. Each file that can be deleted is; each one a message depends on is kept and named with the reason; an id that is unknown, already deleted or out of reach is listed as not found. It cannot be undone. - Scopes: `files:write`. - The app's assistant always asks first. - Toolkit: `files`. **Inputs** - `ids` (`string[]`, required, 1 to 100 items) 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). ### `createFileLink` Publish a file at a public download link that anybody holding it can open, with no sign-in. It answers with the link. The link lives on the files host of domain when that domain has one set up (files.), else on the files host of the address the file belongs to, else on the Nextmail API address. Programs and scripts are refused. revokeFileLink stops a link from working. - Scopes: `files:write`. - The app's assistant always asks first. - Toolkit: `files`. **Inputs** - `id` (`string`, required, 1 to 128 characters) - `domain` (`string`, 3 to 253 characters) 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). ### `revokeFileLink` Stop a public download link from working, for good. Anybody who opens it afterwards, including from mail that already went out, gets nothing. getFile lists the links a file has and their ids. - Scopes: `files:write`. - The app's assistant always asks first. - Toolkit: `files`. **Inputs** - `id` (`string`, required, 1 to 128 characters) - `linkId` (`string`, required, 1 to 128 characters) 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). ### `makeFilePrivate` Make a 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. The file itself stays, and createFileLink can publish it again at a new link. - Scopes: `files:write`. - The app's assistant always asks first. - Toolkit: `files`. **Inputs** - `id` (`string`, required, 1 to 128 characters) 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).