---
title: "Drive"
description: "The drive keeps the team's files next to its mail: a My Drive for every member and shared drives for the team, with folders, uploads of any size (resumable, folders by drag and drop), previews, versions, Trash, sharing…"
url: https://onesend.email/docs/drive/
---
# Drive

The drive keeps the team's files next to its mail: a **My Drive** for every member and **shared drives** for the team, with folders, uploads of any size (resumable, folders by drag and drop), previews, versions, Trash, sharing with members and public links. Files can be attached to messages written in the inbox, and files of received mail saved to the drive.

The drive is part of the inbox: it is off when the inbox is (`ONESEND_INBOX=off`, the cloud edition by default; 403 `inbox_unavailable`), and it needs the server's file storage: the data folder on Node, an R2 bucket bound as `FILES` on Cloudflare Workers (without it, 503 `drive_storage_unavailable`). In the dashboard: **Drive** in the sidebar. In the Mac app: **Drive** in the mail window's sidebar; drop files and folders from Finder on it to upload them.

All endpoints below are under `/v1/drive`. Apps (OAuth, MCP), test-mode keys and keys limited to some mailboxes (agent keys) cannot use the drive (403), and cannot attach drive files to mail either (`driveFileId`, 403 `mailbox_key_cannot_use_drive` for a key limited to mailboxes).

## Drives and who can open them

| Drive | Who opens it |
|---|---|
| My Drive (`kind: my`, `access: personal`) | Only its member. Created the first time they open the drive. |
| Shared drive, `access: workspace` | Every member of the workspace. |
| Shared drive, `access: members` | The members in `accessUserIds`, plus the workspace owners and admins. |

These are the rules of [mailbox access](https://onesend.email/docs/inbox/#who-can-read-a-mailbox), with the same answers: for anyone else a drive, its folders and files do not exist (**404**, never 403), and they are left out of every list, search, Recent, Starred and Shared with me. Owners and admins see every member's My Drive with `GET /drive/drives?all=true` (to delete one, for example of someone who left) but cannot list or open what is in it.

Roles: **viewers** open and download; **editors** also upload, create folders, rename, move, copy, move to Trash, restore and share. Workspace viewers and read-only API keys are viewers everywhere. API keys act with the rights of the member who created them; a key nobody is recorded for reaches only `workspace` drives.

Two things need the editor role of the **drive itself** (the owner of a My Drive; who may edit a shared drive), never a share: **moving an item to another drive** and **deleting it permanently** (403 `drive_editor_only`). Someone a file or folder is shared with as an editor can rename it, move it inside its drive (to a folder they can also edit), move it to Trash and restore it, but cannot take it out of the owner's My Drive into their own or destroy it; they can still make a copy.

**Sharing with members** (`POST /drive/items/{id}/shares` with `userId` or `email`, `role` viewer or editor) lets a member open that file, or that folder and everything in it, wherever it is, My Drive included. Only members of the workspace can be added (400 `unknown_member` otherwise). When a member leaves, what was shared with them stops being shared, they leave members-only drives and the public links they created are revoked; their My Drive stays closed until an admin deletes it.

| Method | Path | Purpose |
|---|---|---|
| GET | `/drive/drives` | Drives the caller can open: My Drive first, then shared drives. |
| POST | `/drive/drives` | `{ "name": "Marketing", "access": "workspace" }` or `"members"` with `accessUserIds`. At most 100 per workspace. |
| GET, PATCH, DELETE | `/drive/drives/{id}` | Rename, change who can open it (admins and the member who created it), delete it with everything in it (in the background). |
| GET | `/drive/drives/{id}/items?parentId=&cursor=&limit=` | A folder's contents (default: the top level), folders first, by name, in pages of up to 100, with the folder, the drive and the breadcrumbs (`path`). |
| GET | `/drive/usage` | `bytes`, `files`, `quotaBytes`, `maxFileBytes`, `chunkSize`, `versionsKept`, `trashDays`. |

## Folders and files

| Method | Path | Purpose |
|---|---|---|
| POST | `/drive/folders` | `{ "driveId", "parentId", "name" }`. 409 `name_taken`. |
| POST | `/drive/folders/ensure` | `{ "driveId", "parentId", "path": ["Photos", "2026"] }`: finds or creates each folder (dropped folder trees). |
| GET, PATCH | `/drive/items/{id}` | Read; `name` renames, `parentId` (null: the top level) and `driveId` move (to another drive: with the editor role of the drive it is in), `starred` stars it for you. |
| POST | `/drive/items/{id}/copy` | A copy of a file's current version, or of a folder with what is in it (at most 1,000 items). |
| POST | `/drive/items/{id}/trash`, `/restore` | Move to Trash, restore. |
| DELETE | `/drive/items/{id}` | Delete permanently an item that is in Trash (409 `not_in_trash` otherwise; in the background for folders). Needs the drive's own editor role. |
| GET | `/drive/search?q=&driveId=` | Names containing `q` in the caller's drives and what is shared with them. |
| GET | `/drive/recent`, `/drive/starred`, `/drive/shared-with-me` | The caller's lists. |
| GET | `/drive/trash?driveId=`, POST `/drive/trash/empty` | Trash (newest first); empty it, at most 1,000 items per call (`remaining` says how many are left). |

Names are 1 to 255 characters without `/`, `\` or control characters, and are never `.` or `..`. A name only labels a row: storage keys are made by the server from ids, so no name reaches a path.

**Trash.** Only the item moved to Trash is marked; what is inside a trashed folder stays as it is and is hidden with it (404 until the folder is restored), so trashing and restoring folders of any size is one change. Items stay in Trash for the workspace's Trash retention (**Inbox settings → Trash and Spam**, `trashRetentionDays`), or 30 days when it has none, then are deleted.

**Versions.** Uploading a file with the name of a file already in the folder adds a version instead of a second file. The newest `ONESEND_DRIVE_VERSIONS` (default 10) are kept. `GET /drive/files/{id}/versions`, `POST …/versions/{versionId}/restore` (the old version becomes the newest), `DELETE …/versions/{versionId}`; `GET /drive/files/{id}/content?version=` downloads one.

## Uploads

Files are uploaded in chunks, like [mail imports](https://onesend.email/docs/inbox/#importing-mail), and an interrupted upload resumes where it stopped:

1. `POST /drive/uploads` `{ "driveId", "parentId", "name", "size", "contentType" }` returns the upload with `chunkSize` (8 MiB) and `totalChunks`.
2. `PUT /drive/uploads/{id}/chunks/{n}` with the bytes (`application/octet-stream`), in order from 0, each exactly `chunkSize` except the last. A chunk that already arrived is accepted again without change; 409 `chunk_out_of_order` names the next one. `GET /drive/uploads/{id}` says how many arrived (`chunks`).
3. The last chunk creates the file (`file` in the response). `DELETE /drive/uploads/{id}` cancels.

Only the person or key that started an upload can send its chunks. Uploads that receive nothing for a day expire and their chunks are deleted, and so does every upload still unfinished **7 days** after it started, however often chunks arrive. At most 200 unfinished uploads per workspace and **50 per member** (409 `too_many_uploads`), and a member's unfinished uploads reserve at most **a quarter of the quota** (at least the largest file size; 413 `member_upload_quota`). A member's own uploads and those of every API key they created count together. So one member cannot hold the whole quota or every upload slot with uploads they never finish.

The dashboard uploads two files at a time with a progress panel, retries failed chunks, and makes the folders of a dropped folder first. After an image is uploaded it makes a small thumbnail in the browser and stores it (`PUT /drive/files/{id}/thumbnail`: PNG, JPEG or WebP, at most 256 KB, checked by its bytes); the server never decodes images. Archives are stored as they are and never unpacked on the server.

## Quotas and limits

| Limit | Default | Setting |
|---|---|---|
| Largest file | 5 GB | `ONESEND_DRIVE_MAX_FILE_MB` (413 `file_too_large`) |
| Storage of a workspace's drives, every version included | 100 GB | `ONESEND_DRIVE_QUOTA_GB` (413 `drive_quota_exceeded`) |
| Versions kept per file | 10 | `ONESEND_DRIVE_VERSIONS` |
| Items in one folder | 10,000 | 409 `folder_full` |
| Folder depth | 32 | 400 `too_deep` |
| Shares per item / active links per item | 100 / 20 | 409 |
| Unfinished uploads | 200 per workspace, 50 per member | 409 `too_many_uploads` |
| Bytes reserved by one member's unfinished uploads | a quarter of the quota (at least the largest file) | 413 `member_upload_quota` |
| Lifetime of an unfinished upload | a day without a chunk, 7 days in all | expired |

An upload reserves its whole size before its first chunk with one conditional update (`bytes ≤ quota − size`), so uploads at the same time can never pass the quota together. Canceled and expired uploads, deleted files and pruned versions give their bytes back. A copy counts its size again.

## Previews, downloads and safe content

`GET /drive/files/{id}/content` streams the file; `Range: bytes=a-b` gives part of it (206, 416 when out of range), for seeking in audio and video.

- **Downloads** (the default, `disposition=attachment`) are `Content-Disposition: attachment` with `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`. The type is the file's own only for the preview allowlist below, otherwise `application/octet-stream`.
- **Previews** (`disposition=inline`) only for raster images (PNG, JPEG, GIF, WebP, AVIF, BMP), PDF, audio, video and text. Text (Markdown and source code included) is always `text/plain; charset=utf-8` and shown as text, never rendered. Inline responses carry `Content-Security-Policy: sandbox` (an opaque origin: no cookies, storage or same-origin requests); PDFs get `sandbox allow-scripts` so the browser's PDF viewer runs, still without the app's origin. The dashboard shows PDFs in a frame sandboxed by that response header; the frame has no `sandbox` attribute of its own, because Chromium's PDF viewer (browsers and the Mac app) shows nothing in one.
- **HTML, SVG, XML and scripts are always downloads** (inline answers 415 `preview_not_available`), whatever type the uploader claimed. The type is decided by the extension and the type together.

## Public links

`POST /drive/items/{id}/links` `{ "permission": "download" | "view", "password": "…", "expiresInDays": 7 }` (or `expiresAt`, at most a year) returns a link `https://<ONESEND_PUBLIC_URL>/share/<token>`:

- The token is 256 random bits. Only its SHA-256 is looked up; the token is kept encrypted (re-encrypted when `ONESEND_SECRET` rotates) so the people who manage the item can copy the link again.
- `view` links show the file in the browser (or a folder's list) and never offer a download; `download` links also offer **Download**. **View only is not copy protection:** a preview is the whole file. Images, PDFs, audio, video and text that can be previewed are served in full (inline, with ranges for media), so anyone with the link can still save them from the browser. Use `view` to discourage downloads, not to prevent them; files that cannot be previewed are not served at all through a `view` link. The share dialog says so under the permission.
- A **folder link** shows that folder and what is in it, nothing above or beside it: every file or folder asked for through the link is checked to be inside the linked folder (404 otherwise).
- **Password** (optional): stored as a scrypt hash. The page asks for it and sets a cookie for that link only (12 hours, bound to the current password: changing it signs everyone out). Wrong passwords are limited to 5 per address and link, then one a minute; 10 wrong passwords from one address in 15 minutes lock **that address** out of the link (the right password too) until the 15 minutes have passed. The link locks for **everyone** only after 100 wrong passwords in a row from all addresses together: for 1 minute, then twice as long each further 100 (at most an hour), recorded as `drive.link_locked`. A right password clears the count. So someone who only knows the link's address cannot keep it locked for the people it was shared with.
- **The creator's access.** A link works only while the member who created it can still edit its item. When they leave the workspace, become a workspace viewer, lose the shared drive (its members changed) or the share that let them edit the item (removed, or changed to viewer), their links on it stop (404) and are revoked (`drive.link_revoked` with `reason: creator_lost_access`). A link created with a key nobody is recorded for works only in `workspace` drives.
- Views and downloads are counted (`views`, `downloads`, `lastUsedAt`). Pages and content are limited to 120 requests per address, then 2 a second (429).
- A link stops working when it is revoked (`DELETE /drive/links/{id}`), expires, its creator can no longer edit its item, its item or a folder above it is in Trash or deleted, its drive is deleted, the workspace is being deleted, or the inbox is turned off: every such link gets the same 404 page.
- `PATCH /drive/links/{id}` changes the permission, the password (`null` removes it) and the expiry.
- In the Mac app the server listens only on the Mac (`127.0.0.1`), so its public links open only there. Share from a self-hosted server for links other people can open.

Link pages follow the other [public pages](https://onesend.email/docs/forms-and-archive/): server-rendered, no scripts, a strict `Content-Security-Policy` (images, media and the PDF frame from the server only), `X-Robots-Tag: noindex`, `Cache-Control: no-store` and `Referrer-Policy: no-referrer`, so the token never reaches another site.

Every change to who can open something is in the audit log: `drive.share_added`, `drive.share_changed`, `drive.share_removed`, `drive.link_created`, `drive.link_changed`, `drive.link_revoked`, `drive.link_locked`, `drive.access_changed`, `drive.drive_created`, `drive.drive_deleted`, `drive.trash_emptied`, `drive.trash_retention`. Entries name the item by its id (the target) and its drive (`driveId`); the item's name only when it is in a shared drive. Names of items in a member's My Drive are never recorded, since owners and admins read the audit log and it is in the workspace export.

## Drive and mail

- **Attach from Drive.** The composer's **From Drive** (web and Mac app) picks drive files. **Attach a copy** sends `{ "driveFileId": "dfi_…" }` in the message's `attachments` (`POST /inbox/compose`, `/reply`, the outbox): the server reads the file's current version, with the usual attachment limits (413 `attachments_too_large` above `ONESEND_INBOX_ATTACHMENTS_MAX_MB`). **Share as link** creates a download link for each file and adds `name: link` lines to the message, for files too large to attach. The sender must be able to open the file (404 otherwise).
- **Save to Drive.** Each file of a received message has **Save to Drive** (`POST /drive/save-attachment` `{ "messageId", "index", "driveId", "parentId" }`): the caller must be able to read the message (mailbox access, connected accounts, agent scopes) and add to the folder; the same quota and versions apply.

MCP tools for the drive are not offered.

## How it runs

- **Storage.** A file is kept in chunks of 8 MiB, each its own object in the server's file storage (`drive/<workspace>/<blob>/<n>`), written as the upload arrives and streamed back chunk by chunk: never whole in memory. Versions point at stored contents (`drive_blobs`), which copies share (`refs`).
- **Listing and search** use the index on (drive, folder, kind, name) with keyset pages. Trash, Recent, Starred and search results are checked in batches: the folders above them are read level by level (one statement per level and 90 ids), so a page costs as many statements as the deepest folder is deep. Lists of ids go 90 to a statement (D1 allows 100 bound parameters).
- **Deleting** (Delete forever, Empty Trash, Trash retention, a deleted drive) marks items `deleting`; the `drive_work` job removes them level by level, files in batches of 50 with their versions, shares, links, stars and thumbnails, then deletes stored contents nobody uses in slices. It stops at its query budget (on D1 the invocation budget, as campaign jobs and mail imports do) or after 20 seconds and continues in a new job. The hourly maintenance applies Trash retention, expires idle uploads and uploads older than 7 days, and restarts lost deletions.
- **Workspace deletion** deletes every stored file of the workspace before the purge empties the tables (the inbox module's `gdpr.purging` hook, called again until it is done).

## Data model and GDPR

Migration `0046_drive`: `drive_drives`, `drive_items`, `drive_versions`, `drive_blobs`, `drive_uploads`, `drive_shares`, `drive_links`, `drive_stars`, `drive_recent`, `drive_usage` (byte counts are floating point columns: files can be larger than 2 GB). Every table has `workspace_id` and is deleted with the workspace.

The workspace data export contains the drives, folders, files (names, sizes, types, versions), shares and links (without token, token hash or password hash), but not file contents, and **nothing that is in a member's My Drive** (like personal mail). Upload bookkeeping, stored-content rows, stars and Recent are not exported.
