Адреса отправителя через API и MCP

TrekMail разделяет две задачи, для которых используются разные учётные данные и разрешения:

1. Интерфейс панели/Ops управляет многоразовыми профилями SMTP и маршрутизацией доменов. Он использует токен tm_live_ с smtp:read или smtp:write.
2. Интерфейс веб-почты/сообщений управляет адресами отправителя, доступными одному почтовому ящику и одному подключённому ящику. Он использует токен tm_msg_ с messages:read, messages:write или messages:send.

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

Кратко

• Если отправлять только с external_account_id, получатели увидят собственный адрес подключённого аккаунта, а письмо будет отправлено через его SMTP-сервер.
• Если также передать привязанный к источнику identity_id, получатели увидят рабочий адрес профиля. TrekMail использует назначенный этому профилю маршрут домена или сохранённый профиль SMTP, а затем сохраняет копию в папке Отправленные подключённого ящика.
• На Starter это можно настроить и использовать в веб-почте. На Pro и Agency процесс также можно автоматизировать через API или MCP. В Nano нет мест для подключённых аккаунтов.

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

Модель маршрутизации

Когда external_account_id передаётся без identity_id, TrekMail отправляет письмо через собственный SMTP-сервер внешнего аккаунта и использует его собственный адрес.

Когда передаются оба значения, TrekMail рассматривает внешний аккаунт как место назначения входящих/отправленных, а профиль как видимый адрес отправителя + маршрут SMTP:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

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

1. Проверка или настройка SMTP в API панели

Используйте токен Ops.

При чтении профиля пароль никогда не возвращается. Endpoint использования позволяет агенту безопасно объяснить последствия до изменения или удаления общего профиля.

Инструменты MCP: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. Просмотр адресов точного входящего ящика

Используйте токен сообщений:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

Ответ содержит относящиеся к источнику identities, все настроенные external_identities, sending_addresses, подходящие send_as_domains, параметр ящика reply_from_policy и, только для ящика владельца аккаунта, сохранённые smtp_profiles, которые можно выбрать напрямую.

MCP: вызовите list_identities с external_account_id.

Размещённый MCP и локальный stdio

У инструментов сообщений есть одно важное различие между транспортами:

• Размещённый HTTP MCP (OAuth): также передавайте mailbox_id при каждом вызове инструмента сообщений. Размещённый сервер использует его для создания краткосрочного токена сообщений именно для этого ящика. Например, вызовите list_identities с { "mailbox_id": 7, "external_account_id": 42 }.
• Самостоятельно размещённый stdio MCP (tm_msg_): не передавайте mailbox_id. Статический токен сообщений уже привязан к одному ящику, поэтому схеме инструмента нужен только external_account_id.

external_account_id никогда не заменяет mailbox_id: он выбирает подключённый входящий ящик внутри уже авторизованного почтового ящика. Инструменты SMTP панели остаются ограниченными аккаунтом и не принимают mailbox_id ни в одном из транспортов.

3. Создание профиля отправителя

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email уже должен быть основным адресом этого ящика или активным псевдонимом с разрешённой отправкой. Его домен должен быть активен и принадлежать тому же аккаунту. smtp_mode: domain использует маршрут домена, настроенный в панели. smtp_mode: profile привязывает профиль отправителя к smtp_connection_id; прямой выбор профиля доступен только ящику владельца аккаунта.

external_account_id является необязательным, и важно точно понимать его назначение:

• Укажите его, если читаете почту этого адреса через подключённый входящий ящик Gmail, Outlook или IMAP. Профиль отправителя будет привязан к этому ящику и сможет использоваться только с ним.
• Не указывайте его, если почта вместо этого пересылается в ящик TrekMail. Это сценарий общего ящика, в котором клиент хранит почту у своего провайдера и пересылает копии в ящик команды. Профиль отправителя принадлежит самому ящику, и его может использовать каждый участник с разрешением на отправку.

Личный подключённый входящий ящик нельзя прикрепить к общему ящику: он доступен только подключившему его человеку. В этом случае не указывайте external_account_id.

MCP: create_identity с kind=send_as. В размещённом MCP укажите родительский mailbox_id, как описано выше.

4. Отправка, создание черновика, планирование, ответ или пересылка

Обычные операции с сообщениями принимают ту же пару источников:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id поддерживается при немедленной отправке, сохранении/обновлении черновика и запланированной отправке. Подготовка ответа/пересылки принимает external_account_id и выбирает подходящий профиль по заголовкам доставки. Выбранный профиль повторно авторизуется при фактическом выполнении сообщения из очереди; отключение его псевдонима, домена, профиля SMTP или подключённого аккаунта останавливает доставку вместо незаметного перехода на другой адрес отправителя.

Инструменты MCP: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all и prepare_forward.

Политика ответа

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient по возможности отвечает с адреса, который получил сообщение. default для обычной почты всегда начинает с адреса ящика по умолчанию. MCP использует set_reply_from_policy.

Правила безопасности и изоляции

• Учётные данные SMTP никогда не попадают в ответ API сообщений или MCP.
• Каждый внешний аккаунт и профиль отправителя ограничен ящиком токена сообщений.
• Подключённый профиль отправителя можно использовать только с его точным external_account_id; принадлежащий ящику профиль можно использовать только без него.
• Адрес отправителя уже должен быть авторизован как адрес ящика или псевдоним с разрешённой отправкой; API не может создавать произвольные адреса отправителя.
• Перед созданием требуется рабочий маршрут, который снова проверяется во время доставки.
• Пользовательские заголовки Reply-To не могут конфликтовать с сохранённым Reply-To профиля отправителя.
• Для изменения профилей отправителя и SMTP через MCP требуется соответствующее разрешение на запись. Администратор локально размещённого MCP может потребовать явного одобрения действий записи; отправка также требует подтверждения для каждого сообщения.

Новые строки областей токена не нужны. Существующие токены smtp:* и messages:* продолжают работать в соответствии с текущими разрешениями.

Какой лимит отправки применяется?

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

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

• Подключённые аккаунты через API и MCP
• Области API и разрешения тарифов
• Обзор REST API TrekMail для разработчиков
• Отправляйте письма с рабочего адреса через Gmail