Drive Bulk File Operations via API/MCP

Bulk operations let an integration act on many Drive files and folders in one request. They are useful for archiving old folders, restoring a mistaken cleanup, moving generated reports, or clearing reviewed trash.

Because bulk actions can touch a lot of data, design them with conservative scopes, previews, and audit review.

What bulk operations can do

Drive supports bulk actions for:

• Trash files and folders.
• Restore files and folders from Trash.
• Move files and folders to a target folder.
• Permanently purge trashed files and folders.

Bulk requests can include up to 5,000 selected IDs. For larger cleanups, run multiple reviewed batches rather than one unbounded job.

Selecting IDs

Use browse, folder tree, search, or select-all helpers to build a list of IDs. MCP includes drive_select_all_ids for workflows that need "everything in this folder" without forcing the agent to paginate manually.

Before executing a destructive batch, have the agent summarize the planned action:

• Target Drive space.
• Number of files and folders.
• Destination folder, if moving.
• Whether the operation is recoverable.
• Required scope and MCP safety gate.

REST endpoints

POST /api/v1/drive/spaces/{space}/bulk:trash
POST /api/v1/drive/spaces/{space}/bulk:restore
POST /api/v1/drive/spaces/{space}/bulk:move
POST /api/v1/drive/spaces/{space}/bulk:purge

Use an Idempotency-Key header for every bulk request. If a retry happens, TrekMail can return the original result instead of repeating the batch.

MCP tools

drive_bulk_trash
drive_bulk_restore
drive_bulk_move
drive_bulk_purge

drive_bulk_purge is permanent and requires the matching purge scope. In MCP it should also be protected by TREKMAIL_ALLOW_DESTRUCTIVE=true.

Safe cleanup pattern

For most automations, use a two-step cleanup:

1. Move old files to an Archive folder or Trash.
2. Wait for human review or a separate scheduled maintenance job before purge.

This keeps the daily agent useful while preserving recovery options.

Permission design

Keep purge in a separate token. If a workflow only archives files, it does not need purge at all.