Turning Drive Off for a Mailbox via API

Storage is pooled across your account, so one person treating Drive as personal cloud storage spends the space everyone else needs for mail. Every mailbox carries a drive_access level that decides how much of Drive its user reaches. This page is the command reference for setting it.

The same setting lives in the dashboard under Mailboxes → (a mailbox) → Limits. It is available on every plan and costs nothing extra.

The three levels

full is the default, and it is what every existing mailbox has. Receiving is never affected: a large attachment someone sends to the mailbox opens from webmail as it always has, at any level.

Required scope

mailboxes:write, the same scope that updates any other mailbox field. Both endpoints below accept an Idempotency-Key header and are safe to retry.

One mailbox

curl -s -X PATCH "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: drive-access-{MAILBOX_ID}-off" \
  -d '{"drive_access":"disabled"}'

The updated mailbox comes back with the new level:

{ "data": { "id": 1701, "email": "sam@example.com", "drive_access": "disabled", "...": "..." } }

drive_access is also returned by GET /api/v1/mailboxes/{id} and by the list endpoint, so you can audit what is set without changing anything.

Many mailboxes at once

curl -s -X POST "https://trekmail.net/api/v1/mailboxes:drive-access" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: drive-access-domain-123-off" \
  -d '{"domain_id":123,"drive_access":"disabled"}'

Pass exactly one selector:

The response tells you what happened:

{ "data": { "drive_access": "disabled", "matched": 24, "updated": 21, "skipped_shared": 3 } }

matched is how many mailboxes the selector found, updated how many actually changed. Mailboxes already on the requested level are matched but not updated, so re-running the call is harmless — useful if you apply a default to new mailboxes on a schedule.

Applying it to new mailboxes

Mailbox creation does not take drive_access; new mailboxes start at full. To provision a mailbox that never had Drive, create it and then set the level:

# 1. create — the server generates the one-time password and returns it once
curl -s -X POST "https://trekmail.net/api/v1/mailboxes" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -d '{"domain_id":123,"local_part":"sam","password_mode":"generated_one_time"}'

# 2. take Drive away, using the id from the response above
curl -s -X PATCH "https://trekmail.net/api/v1/mailboxes/1701" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -d '{"drive_access":"disabled"}'

If you create mailboxes in batches, the simpler pattern is to create them all and then make one bulk call with domain_id.

With an MCP agent

set_mailboxes_drive_access(domain_id=123, drive_access="disabled")

The tool takes the same three selectors as the REST endpoint and returns the same counts. For a single mailbox, update_mailbox(mailbox_id=1701, drive_access="disabled") also works.

Shared mailboxes

Shared mailboxes are refused on the single endpoint with 422 drive_access_not_applicable, and skipped — but still counted — by the bulk endpoint. Nobody logs into a shared mailbox directly: your team opens it from their own mailbox, so the level set on their mailbox is the one that applies. Someone whose Drive you turned off cannot reach a shared mailbox's files either, and cannot use one as a way around the setting. Storing a level on the shared row would look like it was doing something while changing nothing.

What a restricted mailbox sees

The restriction is enforced everywhere, not just hidden in the interface:

• its Drive space is absent from GET /api/v1/drive/spaces
• its files answer 404 when requested by id
• a sync device cannot be created for it — POST /api/v1/drive/devices returns 422 drive_disabled
• in webmail there is no Drive in the sidebar, no upload by drag-and-drop, and no Drive results in search

Nothing is deleted when you change the level. Files already stored stay where they are and the person simply cannot reach them, which also means turning Drive off does not hand the space back on its own. The dashboard's Limits tab shows what a mailbox is holding and can delete those files permanently if you want the space returned.

Errors you may hit