Приостановка входа в ящик через API

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

Тот же элемент управления находится на панели по пути Почтовые ящики → (почтовый ящик) → Лимиты. Он доступен на любом тарифе без дополнительной платы.

Приостановка входа и пауза: разные вызовы

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

Существует и третье состояние, которое нельзя включить ни одним из этих вызовов. Если исходящая активность указывает на неправомерное использование пароля ящика, TrekMail может остановить отправку из этого ящика, не меняя вход и доставку. Тогда попытки отправки возвращают 403 mailbox_sending_paused. Ни :resume, ни :resume-login не снимают это ограничение, как и повторный вызов: нужно изменить пароль, после чего служба поддержки снова включает отправку. См. Почему я не могу отправлять письма?.

Необходимая область доступа

mailboxes:write, та же область, которая позволяет обновлять любое другое поле почтового ящика. Все приведенные ниже endpoints принимают заголовок Idempotency-Key.

Один почтовый ящик

curl -s -X POST "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}:suspend-login" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-{MAILBOX_ID}-invoice-42" \
  -d '{"reason":"Unpaid invoice 42"}'

{ "status": "login_suspended", "message": "Sign-in has been suspended. The mailbox keeps receiving mail." }

Поле reason необязательно и может содержать до 255 символов. Причина отображается для вас на панели и возвращается API; приостановленный пользователь ее не видит.

Чтобы снять приостановку:

curl -s -X POST "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}:resume-login" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: resume-{MAILBOX_ID}"

Чтение состояния

Состояние возвращают и GET /api/v1/mailboxes/{id}, и endpoint списка, поэтому его можно проверить, ничего не меняя:

{ "data": { "id": 1701, "email": "sam@example.com", "status": "active",
            "login_suspended": true,
            "login_suspended_at": "2026-08-16T14:02:11+00:00",
            "login_suspended_reason": "Unpaid invoice 42", "...": "..." } }

Обратите внимание, что значение status остается active. Это не ошибка, которую нужно обходить: ящик работает и принимает почту. Проверяйте login_suspended, чтобы узнать состояние входа, и status, чтобы узнать, работает ли сам ящик.

Несколько почтовых ящиков одновременно

curl -s -X POST "https://trekmail.net/api/v1/mailboxes:login-access" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-domain-123-august" \
  -d '{"domain_id":123,"login_suspended":true,"reason":"Unpaid invoice 42"}'

Передайте ровно один селектор:

Ответ сообщает, что произошло:

{ "data": { "login_suspended": true, "matched": 24, "updated": 21, "skipped": 3 } }

matched показывает число найденных селектором ящиков, updated показывает, сколько из них действительно изменено, а skipped показывает, к скольким применить вызов не удалось. Ящики, которые уже находятся в запрошенном состоянии, считаются найденными, но не обновляются. Поэтому вызов можно безопасно повторять, например если задание биллинга выполняет его каждую ночь.

Укажите "login_suspended": false, чтобы восстановить доступ для того же набора.

С агентом MCP

suspend_mailbox_login(mailbox_id=1701, reason="Unpaid invoice 42")
resume_mailbox_login(mailbox_id=1701)
set_mailboxes_login_access(domain_id=123, login_suspended=true, reason="Unpaid invoice 42")

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

Что происходит с приостановленным ящиком

Приостановка применяется в каждой точке входа, а не просто скрывается в интерфейсе:

• вход в веб-почту отклоняется, а все уже открытые сеансы завершаются
• аутентификация IMAP, POP и SMTP отклоняется, поэтому почтовые приложения перестают работать и отправлять сообщения невозможно
• доступ CalDAV и CardDAV отклоняется, поэтому календарь и контакты перестают синхронизироваться с телефонами и ноутбуками
• токены сообщений (tm_msg_) для ящика отвечают 422 mailbox_login_suspended. Они не отзываются, поэтому снова заработают после восстановления входа
• пароли устройств для синхронизации файлов отзываются безвозвратно; после снятия приостановки создаются новые
• ссылки сброса пароля и коды восстановления перестают работать, а новые нельзя выпустить; сброс пароля не восстанавливает доступ, потому что блокировку вызывает не пароль
• входящая почта доставляется как обычно, а правила пересылки и фильтры продолжают работать

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

Миграция в приостановленный ящик

Миграцию в приостановленный ящик запустить нельзя: POST /api/v1/migrations отвечает 422 mailbox_login_suspended. Импортер входит в систему, чтобы доставить копируемую почту, поэтому задание завершилось бы с ошибкой в процессе. Восстановите вход, выполните миграцию и снова приостановите его, если это по-прежнему необходимо.

Общие почтовые ящики

Endpoint для одного ящика отклоняет общие ящики с ответом 422 mailbox_unavailable, а массовый endpoint пропускает их, но все равно учитывает в подсчете. Никто не входит в общий ящик напрямую: участники команды открывают его из собственных ящиков. Поэтому доступ закрывает приостановка их ящика, в том числе и к общему ящику. Если сохранить приостановку в записи общего ящика, будет казаться, что действие выполнено, хотя ничего не изменится.

Возможные ошибки