Postfach-Anmeldung per API sperren

Durch das Sperren der Anmeldung kann eine Person nicht mehr auf ein Postfach zugreifen, während das Postfach selbst weiterarbeitet. E-Mails werden normal zugestellt und warten dort; nichts wird zurückgewiesen oder geht verloren. Diese Seite ist die Befehlsreferenz für diese Einstellung.

Dieselbe Steuerung finden Sie im Dashboard unter Postfächer → (ein Postfach) → Limits. Sie ist in jedem Tarif ohne zusätzliche Kosten verfügbar.

Sperren oder pausieren: unterschiedliche Aufrufe

Verwenden Sie :suspend-login für einen Kunden, der nicht bezahlt hat, eine Person zwischen zwei Verträgen oder jeden, dessen E-Mails Sie weiterhin auffangen möchten. Verwenden Sie :pause, wenn das Postfach vollständig gestoppt werden soll, einschließlich der Absender.

Es gibt einen dritten Status, den keiner der beiden Aufrufe erreicht. Wenn ausgehende Aktivitäten darauf hindeuten, dass das Passwort eines Postfachs missbraucht wurde, kann TrekMail den Versand dieses Postfachs stoppen und Anmeldung sowie Zustellung unverändert lassen. Sendeversuche geben dann 403 mailbox_sending_paused zurück. Weder :resume noch :resume-login hebt dies auf, und auch eine Wiederholung des Aufrufs hilft nicht: Das Passwort muss geändert werden, anschließend aktiviert der Support den Versand wieder. Siehe Warum kann ich keine E-Mails senden?.

Erforderlicher Berechtigungsumfang

mailboxes:write, derselbe Berechtigungsumfang, mit dem jedes andere Postfachfeld aktualisiert wird. Jeder der folgenden Endpoints akzeptiert einen Idempotency-Key-Header.

Ein Postfach

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 ist optional und darf bis zu 255 Zeichen lang sein. Der Grund wird Ihnen im Dashboard angezeigt und von der API zurückgegeben; der gesperrte Benutzer sieht ihn nie.

So heben Sie die Sperre auf:

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

Status auslesen

Sowohl GET /api/v1/mailboxes/{id} als auch der Listen-Endpoint enthalten den Status, sodass Sie ihn prüfen können, ohne etwas zu ändern:

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

Beachten Sie, dass status weiterhin active ist. Dies ist kein Fehler, den Sie umgehen müssen: Das Postfach ist aktiv und empfängt E-Mails. Lesen Sie login_suspended für die Anmeldung und status, um festzustellen, ob das Postfach selbst läuft.

Mehrere Postfächer gleichzeitig

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

Übergeben Sie genau einen Selektor:

Die Antwort zeigt, was geschehen ist:

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

matched gibt an, wie viele Postfächer der Selektor gefunden hat, updated wie viele tatsächlich geändert wurden und skipped auf wie viele der Aufruf nicht angewendet werden konnte. Postfächer, die sich bereits im angeforderten Status befinden, werden gefunden, aber nicht aktualisiert. Der Aufruf kann daher sicher wiederholt werden, was etwa bei einem nächtlichen Abrechnungsauftrag nützlich ist.

Setzen Sie "login_suspended": false, um dieselbe Auswahl wiederherzustellen.

Mit einem MCP-Agenten

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

Alle drei Tools stehen einem Agenten mit dem erforderlichen Berechtigungsumfang zur Verfügung. Bei einem lokal gehosteten MCP-Server kann der Administrator eine ausdrückliche Genehmigung für Schreibaktionen verlangen. Dies verhindert, dass ein Agent Benutzer versehentlich aussperrt.

Verhalten eines gesperrten Postfachs

Die Sperre wird an jedem Zugang durchgesetzt und nicht nur in der Oberfläche verborgen:

• die Webmail-Anmeldung wird abgewiesen und jede bereits geöffnete Sitzung beendet
• die IMAP-, POP- und SMTP-Authentifizierung wird abgewiesen, sodass E-Mail-Apps nicht mehr funktionieren und nichts gesendet werden kann
• CalDAV und CardDAV werden abgewiesen, sodass Kalender und Kontakte nicht mehr mit Telefonen und Laptops synchronisiert werden
• Nachrichten-Token (tm_msg_) für das Postfach antworten mit 422 mailbox_login_suspended. Sie werden nicht widerrufen und funktionieren wieder, sobald die Anmeldung wiederhergestellt ist
• Gerätepasswörter für die Dateisynchronisierung werden widerrufen, und dieser Widerruf ist endgültig; nach Aufhebung der Sperre werden neue erstellt
• Links zum Zurücksetzen des Passworts und Wiederherstellungscodes funktionieren nicht mehr, und neue können nicht ausgestellt werden; das Zurücksetzen des Passworts stellt den Zugriff nicht wieder her, denn das Passwort verursacht die Sperre nicht
• eingehende E-Mails werden normal zugestellt, und Weiterleitungsregeln sowie Filter laufen weiter

Nichts wird gelöscht. Jede Nachricht, jeder Kontakt, Kalendereintrag und jede Datei bleibt an ihrem Platz. Das Postfach zählt weiterhin zu Ihrem Tarif und dessen Speicher. Es fängt weiterhin E-Mails auf.

Migrationen in ein gesperrtes Postfach

Eine Migration in ein gesperrtes Postfach kann nicht gestartet werden: POST /api/v1/migrations antwortet mit 422 mailbox_login_suspended. Das Importprogramm meldet sich an, um die kopierten E-Mails zuzustellen, weshalb der Auftrag unterwegs scheitern würde. Stellen Sie die Anmeldung wieder her, führen Sie die Migration aus und sperren Sie sie danach erneut, falls dies weiterhin erforderlich ist.

Freigegebene Postfächer

Freigegebene Postfächer werden vom einzelnen Endpoint mit 422 mailbox_unavailable abgewiesen und vom Massen-Endpoint übersprungen, aber dennoch gezählt. Niemand meldet sich direkt bei einem freigegebenen Postfach an: Ihr Team öffnet es aus dem eigenen Postfach. Das Sperren des Postfachs dieser Person schließt daher auch im freigegebenen Postfach den Zugang. Eine Sperre in der freigegebenen Zeile zu speichern, sähe nach einer wirksamen Aktion aus, würde aber nichts ändern.

Mögliche Fehler