Automating File Uploads with Drive API

Upload automation is one of the most useful Drive API workflows. Reports, invoices, generated exports, signed PDFs, and support attachments can land in the right TrekMail Drive folder without manual drag-and-drop.

The safe pattern is simple: check storage, create or choose a folder, initiate upload, transfer bytes, complete upload, and write a useful audit trail.

Recommended scopes

For Account Drive uploads, start with:

• drive:account:read
• drive:account:write

For mailbox Drive uploads, use:

• drive:mailbox:read
• drive:mailbox:write

Avoid share and purge scopes unless the same workflow genuinely needs them. If the upload job also creates public links, add the matching share scope.

Preflight checks

Before uploading a large file, call the storage summary or space usage endpoint. Your integration should handle "quota exceeded" as a normal business result, not as a crash.

Good automation also checks whether the destination folder exists. If not, create it with an idempotency key so retries do not create duplicate folders.

REST upload flow

1. POST /api/v1/drive/spaces/{space}/uploads:initiate with file name, size, optional folder ID, and MIME type.
2. Send file bytes to the returned upload URL or multipart upload URLs.
3. POST /api/v1/drive/uploads/{file}:complete after transfer succeeds.
4. If the transfer fails, call POST /api/v1/drive/uploads/{file}:abort to release the reservation quickly.

Write requests should include Idempotency-Key. Use a stable key per logical file, such as invoice-2026-05-001-upload.

MCP upload flow

For agents, prefer one tool:

drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)

The MCP wrapper handles upload negotiation, transfer, completion, and abort-on-error. Low-level tools are available for custom transfer logic, but most workflows do not need them.

Naming and folder conventions

Use predictable names so humans can browse Drive later:

• Reports/2026/05/monthly-summary.pdf
• Clients/Acme/contracts/acme-renewal-2026.pdf
• Invoices/2026/INV-2026-0042.pdf

If an agent uploads repeated versions, include timestamps or version labels. Avoid overwriting meaning by uploading final.pdf every week.

Failure handling

Plan for these cases:

After upload

If the file is meant for external delivery, create a share link with expiry and download cap. If it is internal, leave it as a normal Drive file. Either way, check AI Agents & API → Audit Log to confirm the token and action sequence.