面向开发者的 TrekMail Drive API 概览

TrekMail Drive API 让可信应用和 AI 智能体可以使用你在控制面板和 Webmail 中看到的同一个文件存储空间。你可以使用它列出文件夹、上传文件、生成公共下载链接、恢复回收站中的项目、审计存储用量，以及自动执行重复的文件工作流，而无需让智能体访问整个账户。

Drive 自动化属于 TrekMail REST API v1。它使用 bearer 令牌、JSON 响应、endpoint 支持时的幂等保护，以及 AI 智能体和 API → 审计日志中显示的同一审计跟踪。Drive 权限模型包含 11 个权限范围，其中包括同步设备密码的独立权限范围。Endpoint 和 MCP 工具目录会不断变化，因此请使用返回的工具列表和 API 响应，确定你的令牌当前可以使用的功能。

可以自动执行的任务

常见的 Drive API 任务包括：

• 将月度报告上传到 Account Drive。
• 创建客户文件夹、添加文件并共享一个下载链接。
• 让智能体搜索邮箱 Drive 空间并总结发生的变化。
• 将旧文件移动到归档文件夹。
• 在意外清理后从回收站恢复文件。
• 在警告用户存储空间即将用尽之前读取 Drive 附加组件状态。

API 有意专注于文件操作。它不能替代计费控制面板，也不提供付款或订阅变更功能。

Account Drive 和 Mailbox Drive

Drive 提供两个存储区域。Account Drive 是公司共享空间，通常用于存放品牌资源、合同、入职材料和团队文件夹。Mailbox Drive 是与 Webmail 内邮箱关联的个人存储空间。

API 请求使用 space 参数标识目标：

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

令牌可以限制为仅访问特定邮箱。如果令牌仅限邮箱 42，针对邮箱 99 的请求会返回类似未找到的响应，而不会泄露其他邮箱的存在。

身份验证和基础 URL

在 Authorization 标头中使用操作令牌：

Authorization: Bearer tm_live_your_token

Drive endpoints 位于：

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

在 AI 智能体和 API → 令牌中创建令牌。只选择工作流需要的 Drive 权限范围。

十一个 Drive 权限范围

上传和大文件

上传采用两步模式。API 首先预留配额并返回上传说明。客户端随后将文件字节发送到上传 URL。最后，API 将上传标记为完成。大文件可以使用分片上传，并在长时间传输过期时刷新各分片 URL。

对于大多数 AI 智能体，MCP drive_file_upload 工具比直接调用底层上传 endpoints 更简单。它可以在一条命令中完成文件大小检测、上传、完成操作，以及失败时中止。

共享链接

共享链接为单个文件创建公共下载 URL。文件太大而无法通过电子邮件发送，或访问权限需要能够撤销时，这类链接很有用。请尽可能设置到期日期和下载次数上限。原始链接令牌仅在创建时返回一次，因此如果工作流需要，请立即保存返回的 URL。

删除和永久清除安全

普通删除操作会将文件和文件夹移入回收站。在恢复、永久清除或产品保留规则将其删除之前，项目都可以恢复。永久删除操作需要永久清除权限范围，并应隔离到单独的令牌中。

Drive 附加组件边界

智能体可以使用 drive:addon:read 读取 Drive 附加组件状态、价格和取消预览。REST 或 MCP 写入工具不支持购买、调整容量或取消 Drive 附加组件。这些操作保留在控制面板中，确保用户有意识地控制存储计费流程。