Suspendre la connexion par API

Suspendre la connexion empêche la personne d'accéder à une boîte mail sans interrompre le fonctionnement de celle-ci. Les e-mails sont distribués normalement et l'y attendent; aucun message n'est renvoyé ni perdu. Cette page constitue la référence des commandes permettant de régler cette option.

La même commande se trouve dans le tableau de bord sous Boîtes mail → (une boîte) → Limites. Elle est disponible avec chaque offre, sans frais supplémentaires.

Suspendre ou mettre en pause: deux appels différents

Utilisez :suspend-login pour un client qui n'a pas payé, une personne entre deux contrats ou toute personne dont vous voulez encore recueillir les e-mails. Utilisez :pause lorsque la boîte doit s'arrêter entièrement, y compris pour les expéditeurs.

Il existe un troisième état qu'aucun de ces appels ne permet d'atteindre. Si l'activité sortante laisse penser que le mot de passe d'une boîte a été utilisé abusivement, TrekMail peut empêcher cette boîte d'envoyer tout en maintenant la connexion et la distribution. Les envois renvoient alors 403 mailbox_sending_paused. Ni :resume ni :resume-login ne l'annule, et répéter l'appel ne suffit pas non plus: il faut changer le mot de passe, puis le support réactive l'envoi. Consultez Pourquoi ne puis-je pas envoyer d'e-mails?.

Autorisation requise

mailboxes:write, la même autorisation que pour la mise à jour de tout autre champ d'une boîte mail. Tous les endpoints ci-dessous acceptent un en-tête Idempotency-Key.

Une boîte mail

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 est facultatif et limité à 255 caractères. Il apparaît dans votre tableau de bord et est renvoyé par l'API; l'utilisateur suspendu ne le voit jamais.

Pour lever la suspension:

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

Lire l'état

GET /api/v1/mailboxes/{id} et l'endpoint de liste renvoient tous deux cet état, ce qui permet de l'auditer sans rien modifier:

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

Notez que status reste active. Ce n'est pas une anomalie à contourner: la boîte est active et reçoit des e-mails. Consultez login_suspended pour la connexion et status pour savoir si la boîte elle-même fonctionne.

Plusieurs boîtes à la fois

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

Transmettez exactement un sélecteur:

La réponse indique ce qui s'est passé:

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

matched correspond au nombre de boîtes trouvées par le sélecteur, updated au nombre de boîtes réellement modifiées et skipped au nombre de boîtes auxquelles l'appel n'a pas pu s'appliquer. Les boîtes déjà dans l'état demandé sont comptabilisées, mais pas mises à jour. Vous pouvez donc répéter l'appel sans risque, par exemple si une tâche de facturation l'exécute chaque nuit.

Définissez "login_suspended": false pour restaurer le même ensemble.

Avec un agent 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")

Les trois outils sont accessibles à un agent disposant de l'autorisation requise. Pour un serveur MCP hébergé localement, son administrateur peut exiger une approbation explicite des actions d'écriture, ce qui empêche un agent de bloquer des utilisateurs par accident.

Effets sur une boîte suspendue

La suspension est appliquée à chaque point d'accès, pas simplement masquée dans l'interface:

• la connexion au webmail est refusée et toute session déjà ouverte est fermée
• l'authentification IMAP, POP et SMTP est refusée, les applications de messagerie cessent donc de fonctionner et aucun envoi n'est possible
• CalDAV et CardDAV sont refusés, le calendrier et les contacts cessent donc de se synchroniser avec les téléphones et les ordinateurs portables
• les jetons de message (tm_msg_) de la boîte répondent 422 mailbox_login_suspended. Ils ne sont pas révoqués et refonctionnent donc après la restauration de la connexion
• les mots de passe d'appareil servant à la synchronisation des fichiers sont révoqués définitivement; de nouveaux mots de passe sont créés une fois la suspension levée
• les liens de réinitialisation du mot de passe et les codes de récupération cessent de fonctionner, et il est impossible d'en émettre de nouveaux; réinitialiser le mot de passe ne rétablit pas l'accès, car le blocage ne vient pas du mot de passe
• les e-mails entrants sont distribués normalement, et les règles de transfert ainsi que les filtres continuent de fonctionner

Rien n'est supprimé. Chaque message, contact, événement de calendrier et fichier reste à sa place, et la boîte continue de compter dans votre offre et son stockage. Elle continue à recueillir les e-mails.

Migrations vers une boîte suspendue

Une migration ne peut pas démarrer vers une boîte suspendue: POST /api/v1/migrations répond 422 mailbox_login_suspended. L'outil d'importation se connecte pour distribuer les e-mails qu'il copie, et la tâche échouerait donc en cours de route. Restaurez la connexion, exécutez la migration, puis suspendez-la à nouveau si nécessaire.

Boîtes partagées

L'endpoint individuel refuse les boîtes partagées avec 422 mailbox_unavailable, tandis que l'endpoint groupé les ignore tout en les comptabilisant. Personne ne se connecte directement à une boîte partagée: votre équipe l'ouvre depuis sa propre boîte. Suspendre la boîte de cette personne ferme donc la porte, y compris dans la boîte partagée. Enregistrer une suspension sur la ligne partagée donnerait l'impression d'agir sans rien changer.

Erreurs possibles