Как отключить Drive для ящика через API

Хранилище общее для всей учётной записи, поэтому человек, который использует Drive как личное облачное хранилище, расходует место, нужное остальным для почты. У каждого ящика есть уровень drive_access, определяющий доступ пользователя к Drive. На этой странице приведена справка по командам для его настройки.

Та же настройка находится в панели управления в разделе Почтовые ящики → (ящик) → Лимиты. Она доступна на любом тарифе без дополнительной платы.

Три уровня

full используется по умолчанию и установлен для всех существующих ящиков. Получение писем не затрагивается: большое вложение, которое кто-либо отправит на этот ящик, открывается в веб-почте как обычно при любом уровне.

Необходимая область доступа

mailboxes:write, та же область, которая позволяет обновлять любое другое поле ящика. Оба endpoint ниже принимают заголовок Idempotency-Key, и их можно безопасно вызывать повторно.

Один ящик

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"}'

Обновлённый ящик возвращается с новым уровнем:

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

Поле drive_access также возвращают GET /api/v1/mailboxes/{id} и endpoint списка, поэтому установленное значение можно проверить без изменений.

Несколько ящиков одновременно

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"}'

Передайте ровно один селектор:

Ответ сообщает о результате:

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

matched показывает, сколько ящиков нашёл селектор, а updated показывает, сколько из них действительно изменилось. Ящики с уже установленным запрошенным уровнем учитываются среди найденных, но не обновляются, поэтому повторный запуск вызова безопасен. Это удобно, когда вы по расписанию применяете стандартное значение к новым ящикам.

Применение к новым ящикам

При создании ящика нельзя передать drive_access; новые ящики начинают с full. Чтобы подготовить ящик, у которого никогда не было Drive, создайте его, а затем задайте уровень:

# 1. Create the mailbox. 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" \
  -H "Idempotency-Key: create-mailbox-sam" \
  -d '{"domain_id":123,"local_part":"sam","password_mode":"generated_one_time"}'

# 2. Turn off Drive using the id returned above.
curl -s -X PATCH "https://trekmail.net/api/v1/mailboxes/1701" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: drive-access-1701-off" \
  -d '{"drive_access":"disabled"}'

Если вы создаёте ящики пакетами, проще сначала создать их все, а затем выполнить один массовый вызов с domain_id.

С агентом MCP

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

Инструмент принимает те же три селектора, что и endpoint REST, и возвращает те же количества. Для одного ящика также работает update_mailbox(mailbox_id=1701, drive_access="disabled").

Общие ящики

Endpoint для одного ящика отклоняет общие ящики с ошибкой 422 drive_access_not_applicable, а массовый endpoint пропускает их, но всё равно учитывает. Никто не входит непосредственно в общий ящик: участники команды открывают его из своих ящиков, поэтому применяется уровень ящика участника. Человек, для которого Drive отключён, не может получить доступ к файлам общего ящика или использовать его для обхода настройки.

Что видит ящик с ограничениями

Ограничение применяется везде, а не просто скрывается в интерфейсе:

• пространство Drive отсутствует в GET /api/v1/drive/spaces
• при запросе файлов по id возвращается 404
• для него нельзя создать устройство синхронизации; POST /api/v1/drive/devices возвращает 422 drive_disabled
• в веб-почте нет Drive на боковой панели, загрузки перетаскиванием и результатов Drive в поиске

При изменении уровня ничего не удаляется. Уже сохранённые файлы остаются на месте, но человек просто не может получить к ним доступ. Это также означает, что само отключение Drive не освобождает место. Вкладка Лимиты в панели управления показывает, что хранится в ящике, и позволяет окончательно удалить эти файлы, если вы хотите вернуть место.

Возможные ошибки