Обзор TrekMail Drive API для разработчиков

TrekMail Drive API позволяет доверенным приложениям и ИИ-агентам работать с тем же файловым хранилищем, которое доступно в Dashboard и веб-почте. Используйте API, чтобы получать списки папок, загружать файлы, создавать общедоступные ссылки для скачивания, восстанавливать элементы из корзины, проверять использование хранилища и автоматизировать повторяющиеся операции с файлами, не предоставляя агенту доступ ко всему аккаунту.

Автоматизация Drive является частью TrekMail REST API v1. Она использует bearer-токены, ответы JSON, защиту идемпотентности там, где её поддерживает endpoint, и тот же журнал аудита, который отображается в разделе ИИ-агенты и API → Журнал аудита. Модель разрешений Drive включает 11 прав, в том числе отдельные права для паролей устройств синхронизации. Каталоги endpoints и инструментов MCP развиваются, поэтому проверяйте возвращённый список инструментов и ответы API, чтобы знать актуальные возможности, доступные вашему токену.

Что можно автоматизировать

Типичные задачи Drive API:

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

API намеренно сосредоточен на файлах. Он не заменяет Dashboard биллинга и не предоставляет операции изменения платежей или подписок.

Drive аккаунта и Drive почтового ящика

В Drive есть два пространства хранения. Drive аккаунта является общим пространством компании. Обычно в нём хранят фирменные материалы, договоры, вводные материалы и командные папки. 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

Endpoints Drive находятся по адресу:

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

Создавайте токены в разделе ИИ-агенты и API → Токены. Выбирайте только те права Drive, которые нужны вашему процессу.

Одиннадцать прав Drive

Загрузка и большие файлы

Загрузка выполняется в два этапа. Сначала API резервирует квоту и возвращает инструкции по загрузке. Затем клиент отправляет байты файла на URL загрузки. Наконец, API отмечает загрузку как завершённую. Для больших файлов можно использовать многочастную загрузку и обновлять URL частей, если длительная передача истекла.

Для большинства ИИ-агентов инструмент MCP drive_file_upload проще прямого вызова низкоуровневых endpoints загрузки. Одна команда определяет размер файла, загружает и завершает его загрузку, а при ошибке отменяет операцию.

Общедоступные ссылки

Ссылки общего доступа создают общедоступные URL для скачивания отдельных файлов. Они полезны, если файл слишком велик для электронной почты или доступ к нему должен быть отзывным. По возможности задавайте дату окончания действия и ограничение скачиваний. Исходный токен ссылки возвращается только один раз при создании, поэтому сразу сохраните полученный URL, если он нужен вашему процессу.

Безопасное и безвозвратное удаление

Обычные операции удаления перемещают файлы и папки в корзину. Элементы можно восстановить, пока они не восстановлены, не удалены безвозвратно или не удалены по правилам хранения продукта. Для безвозвратного удаления нужны отдельные права, которые следует изолировать в специальном токене.

Граница дополнения Drive

Агенты могут читать состояние, цены и предварительные условия отмены дополнения Drive с правом drive:addon:read. Покупка, изменение объёма и отмена дополнения Drive недоступны через инструменты записи REST или MCP. Эти действия выполняются в Dashboard, чтобы биллинг хранилища оставался осознанным процессом под контролем пользователя.

Связанные статьи

• Быстрый старт с Drive API
• Права и разрешения Drive API
• Обзор инструментов Drive MCP
• Руководство по TrekMail Drive