Подключённые аккаунты через API и MCP

Подключённые аккаунты позволяют читать и отправлять письма из внешних почтовых ящиков, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 или любого сервера IMAP через веб-почту. API сообщений и инструменты MCP предоставляют те же возможности программно: можно просматривать, добавлять, проверять, изменять и удалять подключённые аккаунты, а также направлять обычные запросы к сообщениям (просмотр, чтение, отправка, флаги, перемещение, удаление и папки) в подключённый аккаунт вместо собственного ящика токена.

Проще говоря, mailbox_id выбирает ящик TrekMail, от имени которого может действовать агент, а external_account_id выбирает Gmail или другой подключённый к нему ящик. Эти значения не взаимозаменяемы.

Тарифы, лимиты и размер каталога

Для управления подключёнными аккаунтами предусмотрено семь инструментов сообщений. Токен с ограниченными областями доступа видит только доступные ему инструменты, а не весь каталог продукта.

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

• Подключённые аккаунты относятся к функциям веб-почты и используют интерфейс токена сообщений (/api/v1/messages/...). Для авторизации нужен токен сообщений с указанными ниже областями доступа, а не API-токен панели.
• Лимиты тарифа применяются к каждому ящику: Starter 5, Pro 10, Agency 30. Тариф Nano не поддерживает подключённые аккаунты.
• Каждый endpoint ограничен собственным ящиком токена. Токен может видеть и изменять только подключённые аккаунты своего ящика, но не другого.
• Учётные данные и токены OAuth всегда маскируются в ответах. Пароль или пароль приложения можно записать, но нельзя прочитать обратно.
• Аккаунты Outlook.com и Microsoft 365 подключаются через вход Microsoft (OAuth) в интерфейсе веб-почты. После подключения API позволяет управлять ими и использовать их, но не выполняет интерактивный этап согласия Microsoft.

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

Для обращения к подключённому аккаунту в запросе к сообщениям нужна та же область доступа, которая уже требуется этому запросу (например, для просмотра сообщений нужна messages:read, а для отправки нужна messages:send).

Управление подключёнными аккаунтами

Базовый путь: /api/v1/messages/external-accounts

Добавление аккаунта

POST /api/v1/messages/external-accounts
Scope: messages:write

Тело запроса:

Сначала вызовите POST /external-accounts/detect, чтобы автоматически заполнить provider и настройки сервера. Перед сохранением выполняется реальная проверка IMAP + SMTP. Ответ 422 с категорией ошибки (auth, tls, network, transient_throttle) означает, что учётные данные не подошли и ничего не было сохранено.

Обращение к подключённому аккаунту в запросах к сообщениям

Каждый endpoint сообщений, работающий с ящиком, принимает необязательный external_account_id. Укажите его, чтобы выполнить запрос в подключённом аккаунте вместо собственного ящика токена; не указывайте, чтобы использовать сам ящик. Это относится к просмотру, чтению, отправке, ответам, флагам, перемещению, удалению и просмотру папок.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

При отправке только с external_account_id используется собственный SMTP-сервер аккаунта (с SPF/DKIM его провайдера). Если вместо этого передать привязанный к источнику identity_id, будет использован домен или маршрут сохранённого профиля этого адреса отправителя, а копия отправленного письма по-прежнему сохранится в подключённом ящике. Аккаунт должен быть исправен (status: active); для отключённого аккаунта вернётся ошибка с просьбой подключить его заново. См. Адреса отправителя через API и MCP.

Инструменты MCP

Те же возможности доступны ИИ-агентам через MCP (как на закрытом сервере stdio, так и на общедоступном сервере MCP):

Инструменты сообщений list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all и prepare_forward принимают необязательный аргумент external_account_id. Отправка, создание черновиков и планирование также принимают привязанный к источнику identity_id, возвращённый list_identities.

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

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

• Читайте все почтовые аккаунты в одном ящике
• Добавьте аккаунт Outlook.com в TrekMail
• Обзор REST API TrekMail для разработчиков
• Отправляйте письма с рабочего адреса через Gmail