Области API и разрешения тарифов

Области точно определяют, что может делать токен API. Каждый токен содержит набор областей, и API проверяет их при каждом запросе.

Как работают области

При создании токена вы выбираете включаемые области. API применяет к каждому запросу три верхних ограничения:

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

Ошибка указывает, какое ограничение не пройдено. insufficient_scope означает, что область не была выдана учётным данным, scope_blocked_by_membership указывает на более узкую роль пользователя, а scope_blocked_by_entitlement означает, что необходимое право White Label неактивно.

Два уровня областей: OAuth и области API

OAuth поддерживает шесть устаревших объединённых областей, все детальные области API и селекторы tools:*, которые управляют только видимостью. Устаревшие объединения:

Каждое устаревшее объединение OAuth разворачивается в детальные области API, например domains:read и drive:account:write. Новые интеграции могут запрашивать их напрямую. Области White Label намеренно отсутствуют в старых объединениях mail:*, поэтому существующий коннектор не получит управление реселлером после обновления. Он должен явно запросить необходимые области White Label. Селектор tools:white_label ограничивает видимость в MCP, но сам по себе не выдаёт разрешений API.

Три способа подключения и выдача возможностей

Агент или интеграция может подключиться к TrekMail тремя способами, и механизм ограничений у каждого отличается. Это важно, поскольку «флаги возможностей» MCP (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) существуют только в одном из них.

Кратко: размещённый HTTP MCP фильтрует заявленные инструменты по учётным данным OAuth; stdio MCP пересекает области токена с наборами инструментов, режимом только для чтения и локальной защитой; REST API напрямую ограничивается детальными областями токена. Авторизация API во время выполнения остаётся окончательной во всех режимах.

Справочник областей

Аккаунт и биллинг

billing:autopay является единственной областью, которая перемещает деньги, поэтому её стоит прочитать дважды.

Она намеренно отделена от billing:read: подключение, которому разрешено видеть ваш счёт, не должно иметь возможности увеличивать его, а выдача доступа к чтению биллинга не означает согласия на расходы. Область никогда не включается автоматически, токен или подключение получает её только после явной выдачи, и она отсутствует во всех старых объединениях широких областей, поэтому подключение, авторизованное до появления этой области, не может ничего оплачивать.

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

Область доступна на всех тарифах, поскольку кредиты проверки продаются на каждом тарифе, включая Nano.

Домены

Доставка через псевдоним домена доступна начиная со Starter. Токены Starter могут читать сохранённое и текущее состояние; подключение, изменение или удаление через API/MCP требует возможности domains:write тарифа Pro/Agency. Изменения в панели остаются доступны на Starter. См. Псевдонимы домена через API и MCP.

White Label

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

Текущее участие задаёт ещё одно ограничение. Клиент или коллега не может расширить собственную роль, доступ к доменам или пользовательские разрешения, создав более широкий токен. См. Управление командами White Label через API и MCP.

Почтовые ящики

Сообщения (токен сообщений)

Области сообщений принадлежат токенам сообщений (префикс tm_msg_), а не операционным токенам (префикс tm_live_). Токены сообщений создаются через API с помощью операционного токена с областью mailboxes:message-tokens:manage. Помимо обычных ограничений маршрута отправки, у них есть собственная защита API: по умолчанию чтение допускает 30 запросов в минуту и 5,000 успешных чтений в день на токен; отправка допускает 60 запросов в минуту на токен и 100 отправок через API в день для всего ящика. Второй счётчик безопасности токена по умолчанию равен 500 отправкам в день, поэтому обычно действует более низкий лимит ящика.

Все новые конечные точки API веб-интерфейса (контакты, календарь, идентификаторы, шаблоны, заблокированные отправители, черновики, запланированная отправка, папки, вложения) используют существующие три области сообщений; новые области не добавлялись. Существующие токены продолжают работать без изменений.

messages:read не предоставляет доступ на запись. В размещённом OAuth одобрение более широкой возможности messages:send одновременно предоставляет чтение, запись и отправку; созданный вручную токен tm_msg_ сохраняет только выбранные при создании области.

Тикеты поддержки

Starter: через API доступно только чтение. Открывайте тикеты и отвечайте на них в панели.

Настройка SMTP

SMTP настраивается для каждого домена (/api/v1/domains/{id}/smtp), а единое значение по умолчанию для аккаунта (/api/v1/smtp/default) определяет начальную настройку новых доменов. Полный список конечных точек приведён в Обзоре API. Устаревшие конечные точки /api/v1/smtp на уровне аккаунта по-прежнему отвечают для совместимости, но больше не управляют маршрутизацией.

Миграции

Области миграции принадлежат операционным токенам (префикс tm_live_). Starter может просматривать миграции через API и запускать их в панели. Pro и Agency также могут запускать, отменять, повторять и удалять миграции через API и MCP.

Cloudflare

Drive

Области Drive принадлежат операционным токенам. Токен можно ограничить выбранными ящиками, и Drive скроет от него остальные пространства. Покупка, изменение размера и отмена дополнения Drive не являются операциями записи API/MCP; изменения биллинга выполняются в панели.

Nano + дополнение Drive: активное дополнение хранилища Drive предоставляет Nano полный набор областей Drive. Больше ничего не открывается: только Drive и уже доступные Nano области Проверки электронной почты. При отмене дополнения области чтения продолжают работать в течение льготного срока 7 дней, чтобы вы могли завершить скачивание или переход; запись, общий доступ и окончательное удаление блокируются сразу.

Проверка электронной почты

Области Проверки электронной почты доступны на всех тарифах, включая Nano. Единственное ограничение связано с остатком кредитов. Полный справочник конечных точек приведён в API Проверки электронной почты.

Уровни доступа тарифов

Области White Label являются дополнительными и не входят в базовые тарифы Pro или Agency. Они появляются в этих аккаунтах только при активном праве White Label.

Что происходит при понижении тарифа

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

Например, токен с mailboxes:create на тарифе Starter получит 403 с кодом token_scope_blocked_by_plan при попытке создать ящик. Области чтения того же токена продолжат работать.

Чтобы исправить это, отзовите старый токен и создайте новый только с областями, разрешёнными текущим тарифом.

Опасные области

Области mailboxes:delete, domains:delete, migrations:write и cloudflare:delete отмечены в панели как опасные. Токены с этими областями могут инициировать удаление ящиков или доменов, удалять токены Cloudflare или выполнять другие необратимые действия. Подумайте, действительно ли они нужны в вашем сценарии.

Администратор самостоятельно размещённого сервера MCP может требовать TREKMAIL_ALLOW_DESTRUCTIVE=true, прежде чем инструменты удаления станут доступны. Размещённый MCP использует области, одобренные во время OAuth.

Область messages:send разрешает отправлять настоящую почту из ящика. На самостоятельно размещённом сервере MCP для отправки также могут требоваться TREKMAIL_ALLOW_SENDING=true и confirm_send=true при каждом вызове. Подробности приведены в статье Меры безопасности и намерения удаления.

Область migrations:write позволяет запускать миграции почты, подключающиеся к внешним серверам IMAP с сохранёнными учётными данными. На самостоятельно размещённом сервере MCP для записи миграций также могут требоваться TREKMAIL_ALLOW_MIGRATION=true и параметры подтверждения каждого вызова (confirm_start, confirm_cancel, confirm_retry).

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

Области определяют, что может делать токен. Ограничения домена определяют, где он может это делать.

Токен, ограниченный определёнными доменами, видит и изменяет ресурсы только в этих доменах. Это удобно, чтобы предоставить подрядчику или агенту доступ к домену одного клиента, не раскрывая остальные.

Проверка областей выполняется до проверки ограничений домена. Если у токена нет необходимой области, запрос завершается ошибкой 403 независимо от ограничений домена.

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

• 403 "insufficient_scope": у токена нет области, необходимой этой конечной точке. Создайте новый токен с правильными областями.
• 403 "token_scope_blocked_by_plan": ваш тариф больше не разрешает одну или несколько областей токена. Повысьте тариф либо отзовите токен и создайте новый с разрешёнными областями.
• 403 "scope_blocked_by_entitlement": White Label неактивен или была предпринята запись во время льготного срока после отмены. Активируйте его снова перед повторной авторизацией подключения.
• 403 "scope_blocked_by_membership": текущая роль участника или пользовательское разрешение не позволяет действие. Попросите владельца аккаунта изменить участие.
• Некоторые области скрыты в форме создания: ваш тариф не поддерживает эти области. Отображаются только разрешённые области.

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

• Обзор API
• Создание токенов API и управление ими
• Меры безопасности и намерения удаления
• Обзор тарифов TrekMail