API로 메일함의 Drive 액세스 끄기

저장 공간은 계정 전체에서 공유됩니다. 따라서 한 사람이 Drive를 개인 클라우드 저장소처럼 사용하면 다른 사람들이 메일에 써야 할 공간을 소비하게 됩니다. 각 메일함에는 사용자가 Drive의 어느 범위까지 이용할 수 있는지 결정하는 drive_access 수준이 있습니다. 이 페이지는 해당 수준을 설정하는 명령 참조입니다.

같은 설정은 대시보드의 메일함 → (메일함) → 제한에 있습니다. 모든 요금제에서 추가 비용 없이 사용할 수 있습니다.

세 가지 수준

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")

이 도구는 REST endpoint와 동일한 세 선택기를 받고 같은 개수를 반환합니다. 단일 메일함에는 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를 끄는 것만으로는 공간이 저절로 반환되지 않는다는 뜻이기도 합니다. 대시보드의 제한 탭은 메일함이 보관 중인 항목을 보여 주며, 공간을 회수하려는 경우 해당 파일을 영구적으로 삭제할 수 있습니다.

발생할 수 있는 오류