Приостановка входа в ящик через 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. Они не отзываются, поэтому снова заработают после восстановления входа
• все пароли почтовых приложений безвозвратно отзываются; после :resume-login создайте новые, прежде чем снова подключать IMAP, SMTP, приложения календаря или контактов
• пароли устройств для синхронизации файлов отзываются безвозвратно; после снятия приостановки создаются новые
• ссылки сброса пароля и коды восстановления перестают работать, а новые нельзя выпустить; сброс пароля не восстанавливает доступ, потому что блокировку вызывает не пароль
• входящая почта доставляется как обычно, а правила пересылки и фильтры продолжают работать

Возобновление входа сохраняет пароль ящика, но не восстанавливает отозванные пароли приложений. Создайте новые в веб-почте в разделе Настройки, Пароли приложений, в панели управления: Почтовые ящики, (ящик), Безопасность, Пароли приложений, или через API и инструменты MCP для паролей приложений. Почтовые программы могут снова использовать пароль ящика только тогда, когда режим ящика по-прежнему допускает его.

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

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

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

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

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

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