Создание и управление токенами API

Откройте TrekMail в Claude, нажмите Connect, войдите и разрешите доступ. Создавать API-токен не нужно. Проверить разрешения или отключить приложение можно в ИИ-агенты и API → Токены → Подключённые приложения.

Свой бренд White Label: используйте MCP-адрес из кабинета своего бренда и назовите подключение именем бренда. Добавьте его как custom connector: публичная карточка TrekMail выполняет вход на TrekMail и не заменяет подключение вашего бренда.

Токены API определяют, что приложение или агент может делать в вашей учетной записи. У каждого токена есть имя, области доступа, необязательные ограничения доменов и срок действия.

Подключаете клиент MCP? Если он поддерживает авторизацию в браузере, добавьте https://trekmail.net/mcp в качестве удаленного сервера MCP и подтвердите доступ в браузере. Обычно создавать или вставлять токен не требуется. Ручные токены tm_live_ предназначены для скриптов, заданий CI, самостоятельно размещенного MCP и клиентов без поддержки этого процесса. См. Подключение ИИ-агентов (MCP).

Чтение почты одним ключом

На Pro и Agency при создании API-ключа выберите «Чтение почты». Явное разрешение: mailboxes:messages:read; mailboxes:read показывает только адреса ящиков и сведения для настройки. Выберите все ящики, чтобы включить существующие и будущие, либо ограничьте доступ выбранными доменами и ящиками. Существующие ключи автоматически не получают новых прав.

Используйте ключ аккаунта с GET-маршрутами ниже. Для отправки, удаления и других изменений нужны отдельные токены сообщений и разрешения. Hosted MCP принимает OAuth, а не tm_live_ или tm_msg_. Ошибка типа токена подсказывает агенту нужный маршрут или способ авторизации.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Выбор и изменение прав приложения

Откройте сведения об API-ключе или подключённом приложении, выберите «Редактировать доступ», проверьте изменения и подтвердите. Секрет API-ключа сохраняется. Сокращение прав, ресурсов и срока также ограничивает существующие токены ящиков и отменяет ещё не начатые отправки. Доступ новых OAuth-подключений можно сузить сразу; расширение требует нового согласия. Изменение старого подключения отключает его и сохраняет выбор для повторного подключения. У токенов сообщений можно только убрать права или сократить срок.

Перед началом

• Все тарифы, включая Nano, позволяют создавать токены API. Тарифы Nano ограничены областями Email Verifier (verify:read, verify:write).
• Тарифы Starter предоставляют области инфраструктуры только для чтения, а также полный набор областей Drive и Email Verifier. Starter также позволяет управлять пересылкой на панели, но доступ на запись для пересылки через API (mailboxes:forwarding:write) требует Pro или Agency. Pro и Agency открывают все области.
• Владелец может управлять всеми учетными данными аккаунта. Делегированный участник с разрешением на токены API может управлять только созданными им учетными данными и предоставлять только те области и домены, которые уже входят в его членство.
• Совет: Нажмите Начать обзор на странице «ИИ-агенты и API», чтобы быстро ознакомиться с вариантами подключения, токенами, подключенными приложениями и журналом аудита.

Создание токена автоматизации Drive

API Drive и инструменты MCP используют операционные токены (tm_live_...). Выбирайте только те области Drive, которые нужны рабочему процессу:

• Отчеты только для чтения: drive:account:read, drive:mailbox:read или drive:addon:read.
• Автоматическая загрузка: добавьте drive:account:write или drive:mailbox:write.
• Общедоступные ссылки доставки: добавьте drive:account:share или drive:mailbox:share.
• Безвозвратная очистка: используйте drive:account:purge или drive:mailbox:purge только в отдельном токене со строгим контролем.

Покупка, изменение размера и отмена дополнения Drive недоступны через токены API. Агенты могут читать состояние и цены дополнения с областью drive:addon:read, но изменения подписки выполняются на панели.

Создание токена автоматизации White Label

White Label использует пять областей операционного токена: branding:read, branding:write, members:read, members:write и activity:read. Они отображаются, только пока учетная запись имеет доступ к White Label. Область members:write помечена как опасная, поскольку позволяет удалить доступ и отозвать ключи другого человека.

Для интеграции состояния и аудита только для чтения выберите branding:read, members:read и activity:read. Добавляйте branding:write только для настройки бренда и DNS. Добавляйте members:write, только если автоматизация должна приглашать или изменять участников.

В течение льготного периода отмены владелец сохраняет три области чтения для восстановления, а операции записи и делегированные учетные данные White Label перестают работать. Повторная активация не восстанавливает отозванные учетные данные; создайте или авторизуйте новые.

Создание токена

1. Откройте ИИ-агенты и API → Токены.
2. Нажмите Создать токен.
3. Заполните форму:
   • Имя: Метка для идентификации токена (например, «Агент Claude», «Конвейер CI/CD»).
   • Срок действия: Выберите 7 дней, 30 дней, 90 дней, свою дату или вариант без срока.
   • Области: Выберите операции, которые сможет выполнять токен. По умолчанию отмечены все разрешенные области.
   • Ограничение домена: Выберите «Все домены (текущие и будущие)», «Только выбранные домены» или «Все домены (текущие и будущие), кроме…», чтобы исключить несколько доменов.
4. Нажмите Создать токен.

После создания токен в открытом виде отображается один раз. Немедленно скопируйте его или сохраните как файл .txt кнопкой Скачать.

Повторно просмотреть токен невозможно. Надежно сохраните его до закрытия подтверждения.

Создание токена сообщений

Токены сообщений позволяют агентам читать и отправлять почту из конкретного ящика. Они отделены от операционных токенов и создаются программно через API с помощью вашего операционного токена.

Чтобы создать токен сообщений, агент вызывает:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Выберите минимальные области, необходимые рабочему процессу:

Токен в открытом виде (tm_msg_...) возвращается один раз. Добавьте его в конфигурацию MCP как TREKMAIL_MESSAGE_TOKEN.

Токены сообщений доступны на тарифах Pro и Agency. Операционный токен должен иметь область mailboxes:message-tokens:manage.

Для подключенного Gmail или другого внешнего ящика используйте external_account_id. Чтобы получатели вместо него видели авторизованный рабочий адрес, также используйте identity_id, возвращенный endpoint личностей. См. Адреса «От имени» через API и MCP.

Формат токена

TrekMail использует два префикса для различения типов токенов:

Первые 8 символов после префикса сохраняются как видимый префикс на панели для удобной идентификации.

Области доступа

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

• Nano: Только Email Verifier (verify:read, verify:write). При добавлении Drive Storage учетная запись также получает положенные ей возможности API Drive и MCP.
• Starter: Полный доступ к Drive и Email Verifier и доступ только для чтения ко всему остальному (домены, ящики, пересылка, фильтры почты, автоответ, миграции, обращения, SMTP, Cloudflare). Используйте панель для операций записи, которые Starter не предоставляет через API, например для создания миграций, ответов на обращения или изменения автоответа.
• Pro и Agency: Полный доступ. Чтение, запись, создание и удаление во всех семействах, а также токены сообщений для чтения и отправки почты через API.

Области White Label предоставляются как право дополнения, а не как способ обойти таблицу тарифов. Они предлагаются, только когда White Label активен; владелец сохраняет доступ только для чтения в целях восстановления в течение льготного периода отмены.

Описание каждой области приведено в статье Области API и разрешения тарифов.

Ограничения доменов

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

• Только выбранные домены: токен видит отмеченные домены и ничего больше. Домен, добавленный позже, останется недоступным, пока вы не измените токен и не отметите его.
• Все домены (текущие и будущие), кроме…: токен видит все домены, кроме отмеченных, включая добавленные позже. Так агенты не доберутся до почты одного клиента, и менять токен при каждом новом домене не придется.

Ограниченный токен получает ответы 404 при попытке обратиться к ресурсам других доменов; API ведет себя так, будто этих доменов не существует. В обоих случаях токен также не может менять настройки всей учетной записи, которые затронули бы домены вне его доступа, например значение по умолчанию для новых ящиков.

Для участника команды с доступом только к части доменов «кроме…» означает домены этого участника без отмеченных; домены, добавленные в учетную запись позже, в доступ не входят. Если удалить исключенный домен и добавить его снова, он считается новым доменом: исключите его еще раз.

Перевыпуск токена

Перевыпустите токен, если вам снова нужен его секрет или секрет мог утечь. Токен сохраняет название, разрешения, домены, ящики, срок действия и историю в журнале аудита. Меняется только секрет.

1. Откройте ИИ-агенты и API → Токены и нажмите Подробности у нужного токена.
2. Нажмите Перевыпустить.
3. Выберите, когда старый секрет перестанет работать: Сразу, Через 1 час, Через 24 часа, Через 3 дня или Через 7 дней. Старый секрет никогда не работает дольше самого токена.
4. Нажмите Перевыпустить и скопируйте новый секрет. Как и новый токен, он показывается один раз.

Пока старый секрет работает, в подробностях токена видно, когда он отключится, и есть кнопка Отключить сейчас. Замените секрет во всех приложениях до этого времени: запросы со старым секретом после этого получают 401 Unauthorized.

Токены сообщений (tm_msg_...), созданные старым секретом, перестают работать одновременно с ним. Приложение, которое само создаёт токены сообщений, может создать новые с новым секретом. Если секрет мог утечь, выберите Сразу.

Отзыв токена

1. Откройте ИИ-агенты и API → Токены.
2. Найдите токен в списке.
3. Нажмите Отозвать.
4. Подтвердите отзыв.

Отозванные токены немедленно прекращают работать. Любой запрос API с отозванным токеном получает 401 Unauthorized.

Отзыв необратим. Если нужно восстановить доступ, создайте новый токен.

Состояние токена

У токенов есть три состояния:

Используйте фильтр состояния на странице токенов, чтобы просматривать токены по состоянию.

Журнал аудита

Каждое создание, перевыпуск и отзыв токена отображается на вкладке Журнал аудита. События содержат имя токена, действие и время.

Быстрые решения

• «Области недоступны на вашем тарифе»: Тариф не включает эти области. Nano ограничен verify:read и verify:write (добавьте дополнение Drive Storage, чтобы также получить области drive:*). Starter добавляет чтение всех семейств инфраструктуры, а также полный доступ к Drive и Email Verifier. Pro и Agency открывают запись во всех разделах.
• Утерян токен в открытом виде: Восстановить токен невозможно, но его можно перевыпустить: откройте Подробности, нажмите Перевыпустить и скопируйте новый секрет. Настройки токена сохранятся.
• Токен работает, но возвращает 404 для некоторых доменов: Вероятно, на токене установлено ограничение домена. Откройте Подробности токена, нажмите Изменить доступ и добавьте недостающие домены либо переключитесь на «Все домены (текущие и будущие)» или «Все домены (текущие и будущие), кроме…».
• Область White Label возвращает scope_blocked_by_entitlement: Снова активируйте White Label, затем создайте или авторизуйте учетные данные с нужной областью.
• Делегированный токен перестал работать после изменения роли: Сокращение, приостановка или удаление доступа участника немедленно отзывает затронутые учетные данные. Создайте новый токен после того, как владелец восстановит правильный доступ.

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

• Обзор API Drive
• Обзор API
• Области API и разрешения тарифов
• Подключение ИИ-агентов (MCP)
• Управление командами White Label через API и MCP