개발자를 위한 TrekMail Drive API 개요

TrekMail Drive API를 사용하면 신뢰할 수 있는 애플리케이션과 AI 에이전트가 대시보드와 웹메일에 표시되는 동일한 파일 저장소에서 작업할 수 있습니다. 에이전트에게 전체 계정 액세스 권한을 주지 않고 폴더 나열, 파일 업로드, 공개 다운로드 링크 생성, 휴지통 항목 복원, 저장 공간 사용량 감사 및 반복적인 파일 워크플로 자동화에 사용할 수 있습니다.

Drive 자동화는 TrekMail REST API v1의 일부입니다. Bearer 토큰, JSON 응답, 엔드포인트에서 지원하는 경우 멱등성 보호 및 AI 에이전트 및 API → 감사 로그에 표시되는 것과 동일한 감사 추적을 사용합니다. Drive 권한 모델에는 동기화 장치 비밀번호용 별도 범위를 포함하여 11개 범위가 있습니다. 엔드포인트와 MCP 도구 카탈로그는 계속 변경되므로 반환된 도구 목록과 API 응답을 통해 현재 토큰에서 사용할 수 있는 기능을 확인하세요.

자동화할 수 있는 작업

일반적인 Drive API 작업은 다음과 같습니다.

• 월간 보고서를 Account Drive에 업로드합니다.
• 고객 폴더를 만들고 파일을 추가한 다음 다운로드 링크 하나를 공유합니다.
• 에이전트가 Mailbox Drive 공간을 검색하고 변경 사항을 요약하게 합니다.
• 오래된 파일을 보관 폴더로 이동합니다.
• 실수로 정리한 후 휴지통에서 파일을 복원합니다.
• 저장 공간이 거의 찼다고 사용자에게 경고하기 전에 Drive 추가 기능 상태를 읽습니다.

API는 의도적으로 파일 작업에 초점을 맞춥니다. 결제 대시보드를 대체하지 않으며 결제 또는 구독 변경 기능을 제공하지 않습니다.

Account Drive와 Mailbox Drive

Drive에는 두 가지 저장 공간이 있습니다. Account Drive는 회사의 공유 공간입니다. 일반적으로 브랜드 자산, 계약서, 온보딩 자료 및 팀 폴더를 저장합니다. Mailbox Drive는 웹메일의 사서함에 연결된 개인 저장소입니다.

API 요청에서는 space 매개변수로 대상을 식별합니다.

account       # Account Drive
mailbox:42    # mailbox-personal Drive for mailbox ID 42
123           # internal Drive space ID, if your integration stores it

토큰을 특정 사서함으로 제한할 수 있습니다. 토큰이 사서함 42로 제한된 경우 사서함 99에 대한 요청은 다른 사서함이 존재한다는 사실을 노출하는 대신 찾을 수 없음 형식의 응답을 반환합니다.

인증 및 기본 URL

Authorization 헤더에 운영 토큰을 사용합니다.

Authorization: Bearer tm_live_your_token

Drive 엔드포인트의 기본 경로는 다음과 같습니다.

https://trekmail.net/api/v1/drive

AI 에이전트 및 API → 토큰에서 토큰을 만드세요. 워크플로에 필요한 Drive 범위만 선택하세요.

11개 Drive 범위

업로드 및 대용량 파일

업로드는 2단계 패턴을 사용합니다. 먼저 API가 할당량을 예약하고 업로드 지침을 반환합니다. 그런 다음 클라이언트가 파일 바이트를 업로드 URL로 보냅니다. 마지막으로 API가 업로드를 완료로 표시합니다. 대용량 파일은 멀티파트 업로드를 사용할 수 있으며 전송 시간이 길어져 만료되면 파트 URL을 새로 고칠 수 있습니다.

대부분의 AI 에이전트에는 저수준 업로드 엔드포인트를 직접 호출하는 것보다 MCP drive_file_upload 도구가 더 간편합니다. 하나의 명령으로 파일 크기 감지, 업로드, 완료 및 실패 시 중단을 처리합니다.

공유 링크

공유 링크는 개별 파일의 공개 다운로드 URL을 만듭니다. 파일이 이메일로 보내기에는 너무 크거나 액세스를 해지할 수 있어야 할 때 유용합니다. 가능하면 만료일과 다운로드 횟수 제한을 설정하세요. 원시 링크 토큰은 생성할 때 한 번만 반환되므로 워크플로에 필요하면 반환된 URL을 즉시 저장하세요.

삭제 및 영구 삭제 안전성

일반 삭제 작업은 파일과 폴더를 휴지통으로 이동합니다. 항목은 복원되거나 영구 삭제되거나 제품의 보존 규칙에 따라 제거될 때까지 복구할 수 있습니다. 영구 삭제 작업에는 영구 삭제 범위가 필요하며 별도의 토큰으로 분리해야 합니다.

Drive 추가 기능 경계

에이전트는 drive:addon:read를 사용해 Drive 추가 기능 상태, 가격 및 취소 미리 보기를 읽을 수 있습니다. REST 또는 MCP 쓰기 도구로는 Drive 추가 기능을 구매하거나 용량을 변경하거나 취소할 수 없습니다. 저장 공간 결제가 사용자의 의도적인 통제 아래 유지되도록 이러한 작업은 대시보드 안에서만 가능합니다.