Sospendere l'accesso alla casella via API

La sospensione dell'accesso impedisce a una persona di entrare in una casella mentre la casella stessa continua a funzionare. Le email vengono consegnate normalmente e restano in attesa; nulla viene respinto o perso. Questa pagina è il riferimento dei comandi per configurare questa opzione.

Lo stesso controllo si trova nella dashboard in Caselle → (una casella) → Limiti. È disponibile con ogni piano e non comporta costi aggiuntivi.

Sospendere o mettere in pausa: chiamate diverse

Usa :suspend-login per un cliente che non ha pagato, una persona tra due contratti o chiunque la cui posta debba ancora essere raccolta. Usa :pause quando la casella deve fermarsi completamente, anche per i mittenti.

Esiste un terzo stato che nessuna delle due chiamate consente di raggiungere. Se l'attività in uscita fa pensare che la password di una casella sia stata usata impropriamente, TrekMail può bloccare l'invio da quella casella lasciando invariati accesso e consegna. Gli invii restituiscono quindi 403 mailbox_sending_paused. Né :resume né :resume-login rimuovono il blocco, e nemmeno ripetere la chiamata: occorre cambiare la password, poi l'assistenza riattiva l'invio. Consulta Perché non riesco a inviare email?.

Ambito richiesto

mailboxes:write, lo stesso ambito che aggiorna qualsiasi altro campo della casella. Tutti gli endpoint seguenti accettano un'intestazione Idempotency-Key.

Una casella

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 è facoltativo e può contenere fino a 255 caratteri. Viene mostrato nella dashboard e restituito dall'API; l'utente sospeso non lo vede mai.

Per rimuovere la sospensione:

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

Leggere lo stato

Sia GET /api/v1/mailboxes/{id} sia l'endpoint di elenco includono lo stato, così puoi verificarlo senza modificare nulla:

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

Nota che status rimane active. Non è un errore da aggirare: la casella è attiva e riceve posta. Leggi login_suspended per l'accesso e status per sapere se la casella stessa è in funzione.

Più caselle contemporaneamente

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

Passa esattamente un selettore:

La risposta indica cosa è successo:

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

matched indica quante caselle ha trovato il selettore, updated quante sono state effettivamente modificate e skipped a quante non è stato possibile applicare la chiamata. Le caselle già nello stato richiesto vengono conteggiate, ma non aggiornate. La chiamata può quindi essere ripetuta senza rischi, una possibilità utile se un'attività di fatturazione la esegue ogni notte.

Imposta "login_suspended": false per ripristinare lo stesso gruppo.

Con un agente 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")

Tutti e tre gli strumenti sono disponibili per un agente con l'ambito richiesto. Per un server MCP ospitato localmente, l'amministratore può richiedere un'approvazione esplicita per le azioni di scrittura, evitando che un agente blocchi accidentalmente gli utenti.

Cosa fa una casella sospesa

La sospensione viene applicata a ogni punto di accesso, non semplicemente nascosta nell'interfaccia:

• l'accesso alla webmail viene rifiutato e qualsiasi sessione già aperta viene terminata
• l'autenticazione IMAP, POP e SMTP viene rifiutata, quindi le app di posta smettono di funzionare e non è possibile inviare nulla
• CalDAV e CardDAV vengono rifiutati, quindi calendario e contatti smettono di sincronizzarsi con telefoni e portatili
• i token dei messaggi (tm_msg_) della casella rispondono 422 mailbox_login_suspended. Non vengono revocati, quindi tornano a funzionare quando l'accesso viene ripristinato
• le password dei dispositivi per la sincronizzazione dei file vengono revocate definitivamente; ne vengono create di nuove dopo la rimozione della sospensione
• i link per reimpostare la password e i codici di recupero smettono di funzionare, e non è possibile emetterne di nuovi; reimpostare la password non ripristina l'accesso, perché non è la password a bloccarlo
• la posta in arrivo viene consegnata normalmente, e le regole di inoltro e i filtri continuano a funzionare

Non viene eliminato nulla. Ogni messaggio, contatto, evento del calendario e file resta al proprio posto, e la casella continua a contare ai fini del piano e del relativo spazio di archiviazione. Continua a raccogliere la posta.

Migrazioni verso una casella sospesa

Non è possibile avviare una migrazione verso una casella sospesa: POST /api/v1/migrations risponde 422 mailbox_login_suspended. Lo strumento di importazione accede per consegnare la posta copiata, quindi il processo non andrebbe a buon fine. Ripristina l'accesso, esegui la migrazione e sospendilo di nuovo se è ancora necessario.

Caselle condivise

Le caselle condivise vengono rifiutate dall'endpoint singolo con 422 mailbox_unavailable e ignorate, pur restando conteggiate, dall'endpoint collettivo. Nessuno accede direttamente a una casella condivisa: il team la apre dalla propria casella, quindi è la sospensione della casella di quella persona a chiudere l'accesso, anche nella casella condivisa. Registrare una sospensione sulla riga condivisa sembrerebbe produrre un effetto senza cambiare nulla.

Errori possibili