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サーバーでは、管理者が書き込み操作に明示的な承認を必須にできます。これにより、エージェントが誤って利用者を締め出すことを防げます。

ログインを停止したメールボックスの動作

停止は単に画面上で隠すのではなく、すべての入口で適用されます。

• Webメールへのログインは拒否され、すでに開いているセッションも終了します
• IMAP、POP、SMTP認証は拒否されるため、メールアプリは動作を停止し、何も送信できません
• CalDAVとCardDAVは拒否されるため、カレンダーと連絡先はスマートフォンやノートパソコンと同期しなくなります
• メールボックスのメッセージトークン (tm_msg_) は 422 mailbox_login_suspended を返します。トークン自体は取り消されないため、ログインを復元すると再び動作します
• ファイル同期用のデバイスパスワードは取り消され、この取り消しは元に戻せません。停止を解除した後に新しいパスワードを作成します
• パスワード再設定リンクとリカバリーコードは機能しなくなり、新しいものも発行できません。アクセスを妨げているのはパスワードではないため、パスワードを再設定してもアクセスは復元されません
• 受信メールは通常どおり配信され、転送ルールとフィルターも動作を続けます

何も削除されません。すべてのメッセージ、連絡先、カレンダー項目、ファイルは元の場所に残ります。メールボックスは引き続きプランとそのストレージに数えられ、メールを受け取り続けます。

ログイン停止中のメールボックスへの移行

ログイン停止中のメールボックスへの移行は開始できません。POST /api/v1/migrations は 422 mailbox_login_suspended を返します。インポーターはコピーしたメールを配信するためにログインするので、ジョブは途中で失敗します。ログインを復元して移行を実行し、必要であれば再び停止してください。

共有メールボックス

単一メールボックス用 endpoint は共有メールボックスを 422 mailbox_unavailable で拒否します。一括 endpoint は共有メールボックスをスキップしますが、件数には含めます。共有メールボックスに直接ログインする人はいません。チームは自分のメールボックスから共有メールボックスを開くため、その利用者自身のメールボックスへのログインを停止すると入口が閉じ、共有メールボックスにも入れなくなります。共有行に停止状態を保存しても、効果があるように見えるだけで何も変わりません。

発生する可能性があるエラー