Drive API Overview

The TrekMail Drive API lets trusted applications and AI agents work with the same file storage you see in the dashboard and webmail. Use it to list folders, upload files, generate public download links, restore trashed items, audit storage usage, and automate repetitive file workflows without giving an agent access to your whole account.

Drive automation is part of the TrekMail REST API v1. It uses bearer tokens, JSON responses, idempotency keys on write operations, and the same audit trail shown under AI Agents & API → Audit Log. The Drive release adds 39 REST endpoints, 9 Drive scopes, and 38 MCP tools. The TrekMail MCP server now exposes 181 tools in total.

What you can automate

Typical Drive API jobs include:

• Upload monthly reports into Account Drive.
• Create a client folder, add files, and share one download link.
• Let an agent search mailbox Drive spaces and summarize what changed.
• Move old files into an archive folder.
• Restore files from Trash after an accidental cleanup.
• Read Drive Add-on status before warning a user that storage is nearly full.

The API is intentionally file-focused. It does not replace the billing dashboard and it does not expose payment or subscription changes.

Account Drive and mailbox Drive

Drive has two storage surfaces. Account Drive is the shared company space. It is usually where brand assets, contracts, onboarding material, and team folders belong. Mailbox Drive is personal storage attached to a mailbox inside webmail.

API requests identify the target with a space parameter:

account       # Account Drive
mailbox:42    # mailbox-personal Drive for mailbox ID 42
123           # internal Drive space ID, if your integration stores it

Tokens can be constrained to specific mailboxes. If a token is limited to mailbox 42, requests for mailbox 99 return a not-found style response instead of leaking that the other mailbox exists.

Authentication and base URL

Use an ops token in the Authorization header:

Authorization: Bearer tm_live_your_token

Drive endpoints live under:

https://trekmail.net/api/v1/drive

Create tokens from AI Agents & API → Tokens. Choose only the Drive scopes your workflow needs.

The nine Drive scopes

Uploads and large files

Uploads use a two-step pattern. First the API reserves quota and returns upload instructions. Your client then sends file bytes to the upload URL. Finally, the API marks the upload complete. Large files can use multipart upload and refresh part URLs if a long transfer expires.

For most AI agents, the MCP drive_file_upload tool is easier than calling low-level upload endpoints directly. It handles file size detection, upload, completion, and abort-on-failure in one command.

Share links

Share links create public download URLs for individual files. They are useful when a file is too large for email or when access should be revocable. Set an expiry date and download cap whenever possible. The raw link token is returned only once, at creation time, so store the returned URL immediately if your workflow needs it.

Delete and purge safety

Normal delete operations move files and folders to Trash. Items remain recoverable until they are restored, purged, or removed by the product's retention rules. Permanent delete operations require purge scopes and should be isolated in a separate token.

Drive Add-on boundary

Agents may read Drive Add-on status, pricing, and cancellation preview with drive:addon:read. Buying, resizing, or canceling the Drive Add-on is not available through REST or MCP write tools. Those actions stay inside the dashboard so storage billing remains a deliberate user-controlled flow.