Управление командами White Label через API и MCP

Аккаунтами White Label можно управлять, не возвращаясь к панели. REST API и сервер MCP охватывают состояние настройки аккаунта, клиентов и участников команды, роли, доступ к доменам, приглашения, блокировки, удаления, восстановления, лимиты хранилища клиентов и историю действий. Оформление бренда входит в тот же набор инструментов White Label и описано в отдельном руководстве по брендингу.

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

Доступные возможности

Полный каталог MCP теперь содержит 284 инструмента через stdio и до 283 инструмента через размещенный HTTP. White Label добавляет 23 инструмента: семь для брендинга, 13 для управления аккаунтом, участниками и действиями и три для лимитов хранилища клиентов.

Эти инструменты загружаются не для всех. Перед формированием tools/list TrekMail проверяет текущее право аккаунта на White Label, актуальное членство пользователя, токен или разрешение OAuth, ограничения доменов, выбранные наборы инструментов и локальные настройки безопасности. Подключение без доступа к White Label вообще не получает схемы.

Состояния права доступа

При наличии доступа к White Label на чтение вызовите GET /api/v1/white-label или инструмент get_white_label, чтобы отличить active от режима grace только для чтения, а также увидеть ход настройки и срок окончания льготного периода. Недоступный аккаунт не может вызвать этот endpoint: если сохраненные учетные данные все еще содержат область White Label, которой аккаунт больше не может пользоваться, API возвращает scope_blocked_by_entitlement и объясняет, где ее повторно активировать.

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

Endpoint действий участника требует одновременно activity:read и members:read, поскольку его ответ содержит как запись участника, так и действия. Размещенное подключение OAuth использует селектор tools:white_label для запроса этого семейства инструментов; эффективные области REST по-прежнему ограничены аккаунтом и членством.

Для самостоятельно размещенного сервера MCP добавьте white_label в TREKMAIL_TOOLSETS, если используется список разрешенных наборов инструментов. Инструменты записи также соблюдают описанные ниже локальные ограничения безопасности.

Endpoints REST

Все пути находятся под https://trekmail.net/api/v1.

Для каждой операции записи в этой таблице требуется заголовок Idempotency-Key. Повторение того же запроса с тем же ключом возвращает исходный безопасный результат; одноразовые секреты в повторе, например токен приглашения, скрываются. Повторное использование ключа с другим телом возвращает idempotency_mismatch.

Сначала прочитайте каталог доступа

Не задавайте разрешения ролей в коде интеграции. Вызывайте каталог доступа перед приглашением или изменением доступа. Его флаги grantable отражают текущее членство вызывающего пользователя и могут измениться, когда владелец корректирует это членство.

Сейчас для новых приглашений предлагаются следующие роли:

• client - управляет назначенными доменами и почтовыми ящиками, не видя конфиденциальных отношений реселлера с TrekMail.
• webmail_only - отображается в списке команды, но не получает разрешений панели.
• domain_admin - управляет назначенными доменами и их DNS, но не почтовыми ящиками.
• mailbox_operator - управляет почтовыми ящиками в назначенных доменах, но не самими доменами.
• read_only - может просматривать разрешенную часть аккаунта без внесения изменений.
• custom - получает только разрешения, перечисленные в permissions.

Некоторым ролям требуются явно заданные domain_ids; другие могут использовать all_domains. Каталог доступа указывает применимое правило. Если вызывающий пользователь попытается предоставить более широкую роль, разрешение или набор доменов, TrekMail вернет scope_blocked_by_membership, а не будет незаметно сужать приглашение.

Приглашение клиента

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

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

Для пользовательской роли прочитайте grantable_permissions из каталога доступа и отправьте выбранные значения в permissions. Требуется хотя бы одно разрешение.

Отслеживание состояния участника

Каждый ответ об участнике содержит allowed_operations. Используйте этот список вместо предположений:

• Ожидающее приглашение можно обновить, приостановить, отправить повторно или удалить.
• Активного участника можно обновить, приостановить или удалить.
• Приостановленного участника можно обновить, активировать или удалить.
• Удаленного участника можно восстановить.
• Строка владельца видна для контекста, но ее нельзя изменить через эти endpoints.

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

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

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

Границы действий и конфиденциальности

GET /white-label/activity возвращает приглашения, изменения ролей и доменов, блокировки, удаления, восстановления и связанные действия безопасности. Используйте фильтры action, member_id и per_page.

GET /white-label/members/{id}/activity объединяет действия участника в аккаунте с недавними входами, включая время, IP-адрес, примерное местоположение, браузер, операционную систему и тип устройства. Этот маршрут намеренно требует обе области чтения. Вызывающие пользователи с ограничениями по доменам могут запрашивать только участников, полностью находящихся в пределах их доменной границы; недоступный участник возвращается как 404, поэтому endpoint не раскрывает существование другого клиента или арендатора.

Лимиты хранилища клиентов

Лимит хранилища клиента дает доменам клиента один общий объем места в MB для их почтовых ящиков и Drive. Как это работает в панели, описано в статье Свой лимит хранилища для каждого клиента. Лимит, доменов которого нет ни у кого в команде, например созданный здесь до приглашения клиента, показан на странице Команда и клиенты в разделе Лимиты хранилища без клиента.

• Чтение требует members:read. Вызывающая сторона, ограниченная частью доменов, видит только те лимиты, которые действуют исключительно на ее собственные домены. Лимит другого клиента или лимит, который действует и на недоступный ей домен, не попадает в список, а запрос к нему возвращает 404, как к несуществующему ID.
• Изменение требует members:write и вызывающей стороны, которая видит все домены аккаунта. Участник, ограниченный частью доменов, получает 403 scope_blocked_by_membership; ключ, ограниченный частью доменов, получает 403 token_resource_constrained.
• POST работает так же, как страница «Команда и клиенты»: домены без лимита получают новый (201); если у доменов уже один общий лимит, меняется он, а указанные домены без лимита присоединяются к нему (200).
• PATCH принимает storage_limit_mb, domain_ids или оба поля. domain_ids заменяет весь набор, а домены, которых в нем нет, снова используют хранилище аккаунта.
• Каждый лимит возвращает storage_limit_mb, domain_ids, allocated_mb (фиксированные размеры ящиков), pending_invites_mb (фиксированные размеры открытых приглашений), pool_mb (сколько делят ящики с общим хранилищем), used_bytes и member_ids.

В каждой записи участника есть client_limit: единственный лимит, под которым находятся все домены участника, с полями id, storage_limit_mb, allocated_mb и used_bytes, или null. Для вызывающей стороны, ограниченной частью доменов, он также равен null, если этот лимит действует и на недоступный ей домен.

Собственный размер ящика задается через PATCH /mailboxes/{id}/storage (mailboxes:write) или инструментом set_mailbox_storage; оба описаны в обзоре REST API.

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

Для инструментов приглашения требуется TREKMAIL_ALLOW_SENDING=true в самостоятельно размещенном MCP stdio. Для инструментов изменения доступа и инструментов лимитов хранилища клиентов требуется TREKMAIL_ALLOW_DESTRUCTIVE=true; для удаления участника или лимита также требуется confirm_remove=true. У set_mailbox_storage, который не входит в набор White Label, то же требование. Эти переключатели являются локальными средствами безопасности, а не дополнительными разрешениями API. Размещенный MCP применяет собственную утвержденную политику безопасности.

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

Безопасный процесс автоматизации

1. Вызовите get_white_label. Остановитесь при scope_blocked_by_entitlement; в успешном ответе grace продолжайте только чтение.
2. Вызовите get_white_label_access_catalog непосредственно перед предоставлением доступа.
3. Получите список или прочитайте данные целевого участника перед изменением.
4. Проверьте allowed_operations, нужную роль, разрешения и идентификаторы доменов.
5. Используйте стабильный ключ идемпотентности для записи.
6. Снова прочитайте данные участника и сообщите итоговое состояние и фактические разрешения.
7. Проверьте действия White Label, когда потребуется аудиторская запись об изменении.

Ошибки с указанием дальнейших действий

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

• Руководство по API и MCP для брендинга White Label
• Области API и разрешения тарифов
• Создание и управление токенами API
• Подключение ИИ-агентов к TrekMail через MCP
• Свой лимит хранилища для каждого клиента