Docs / Inbox, calendar and 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

DriveWho opens it
My Drive (kind: my, access: personal)Only its member. Created the first time they open the drive.
Shared drive, access: workspaceEvery member of the workspace.
Shared drive, access: membersThe members in accessUserIds, plus the workspace owners and admins.

These are the rules of mailbox access, 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.

MethodPathPurpose
GET/drive/drivesDrives 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/usagebytes, files, quotaBytes, maxFileBytes, chunkSize, versionsKept, trashDays.

Folders and files

MethodPathPurpose
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}/copyA 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, /restoreMove 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-meThe caller's lists.
GET/drive/trash?driveId=, POST /drive/trash/emptyTrash (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, 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

LimitDefaultSetting
Largest file5 GBONESEND_DRIVE_MAX_FILE_MB (413 file_too_large)
Storage of a workspace's drives, every version included100 GBONESEND_DRIVE_QUOTA_GB (413 drive_quota_exceeded)
Versions kept per file10ONESEND_DRIVE_VERSIONS
Items in one folder10,000409 folder_full
Folder depth32400 too_deep
Shares per item / active links per item100 / 20409
Unfinished uploads200 per workspace, 50 per member409 too_many_uploads
Bytes reserved by one member's unfinished uploadsa quarter of the quota (at least the largest file)413 member_upload_quota
Lifetime of an unfinished uploada day without a chunk, 7 days in allexpired

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.

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: 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.