通过 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 会跳过共享邮箱，但仍将其计入数量。用户不会直接登录共享邮箱：团队成员从自己的邮箱中打开它。因此，应暂停该成员自己的邮箱来关闭访问权限，这也会阻止其访问共享邮箱。将暂停状态存储在共享邮箱记录中看似生效，实际不会改变任何内容。

可能遇到的错误