Suspending Mailbox Sign-In via API

Suspending sign-in stops the person from getting into a mailbox while the mailbox itself keeps working. Mail is delivered as normal and waits for them; nothing bounces and nothing is lost. This page is the command reference for setting it.

The same control lives in the dashboard under Mailboxes → (a mailbox) → Limits. It is available on every plan and costs nothing extra.

Suspend or pause — they are not the same call

Use :suspend-login for a client who has not paid or a person between contracts — anyone whose mail you still want to catch. Use :pause when the mailbox should stop entirely, senders included.

Required scope

mailboxes:write, the same scope that updates any other mailbox field. Every endpoint below accepts an Idempotency-Key header.

One mailbox

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 is optional and up to 255 characters. It is shown to you in the dashboard and returned by the API; the suspended user never sees it.

To lift it:

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}"

Reading the state

GET /api/v1/mailboxes/{id} and the list endpoint both carry it, so you can audit without changing anything:

{ "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", "...": "..." } }

Note that status stays active. That is not a bug to work around: the mailbox is live and receiving. Read login_suspended for sign-in, and status for whether the mailbox itself is running.

Many mailboxes at once

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"}'

Pass exactly one selector:

The response tells you what happened:

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

matched is how many mailboxes the selector found, updated how many actually changed, skipped how many the call could not apply to. Mailboxes already in the requested state are matched but not updated, so the call is safe to repeat — useful if a billing job runs it nightly.

Set "login_suspended": false to restore the same set.

With an MCP agent

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")

All three are gated behind TREKMAIL_ALLOW_DESTRUCTIVE, like pause_mailbox — an agent cannot lock your users out unless you have enabled destructive tools for that connection.

What a suspended mailbox does

The suspension is enforced at every door, not hidden in the interface:

• webmail sign-in is refused, and any session already open is ended
• IMAP, POP and SMTP authentication is refused, so mail apps stop working and nothing can be sent
• CalDAV and CardDAV are refused, so calendar and contacts stop syncing to phones and laptops
• message tokens (tm_msg_) for the mailbox answer 422 mailbox_login_suspended — they are not revoked, so they work again once sign-in is restored
• device passwords for file sync are revoked, and revoking them is permanent — new ones are created after the suspension is lifted
• password-reset links and recovery codes stop working, and new ones cannot be issued; resetting the password does not restore access, because the password is not what is blocking it
• incoming mail is delivered normally, and forwarding rules and filters keep running

Nothing is deleted. Every message, contact, calendar entry and file stays where it is, and the mailbox keeps counting toward your plan and its storage — it is still catching mail.

Migrations into a suspended mailbox

A migration cannot start into a suspended mailbox: POST /api/v1/migrations answers 422 mailbox_login_suspended. The importer signs in to deliver the mail it copies, so the job would fail partway. Restore sign-in, run the migration, suspend again if you still need to.

Shared mailboxes

Shared mailboxes are refused on the single endpoint with 422 mailbox_unavailable, and skipped — but still counted — by the bulk endpoint. Nobody signs in to a shared mailbox directly: your team opens it from their own mailbox, so suspending their mailbox is what closes the door, and it closes it in the shared mailbox too. Storing a suspension on the shared row would look like it was doing something while changing nothing.

Errors you may hit