Sicherheitsvorkehrungen und Löschabsichten

Die TrekMail-API verhindert versehentlichen Datenverlust. Destruktive Vorgänge erfordern mehrere Bestätigungsschritte, Ratenlimits verhindern Massenfehler und jede Aktion wird protokolliert.

Papierkorb. Wenn Sie die Löschabsicht für eine Mailbox bestätigen, wird die Mailbox jetzt in einen Papierkorb mit 7 Tagen Aufbewahrung verschoben, der im Dashboard als Kürzlich gelöscht angezeigt wird. Sie wird nicht sofort zerstört. Sie können Mailboxen im Papierkorb auflisten und innerhalb dieses Zeitraums wiederherstellen:

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

Nach Ablauf der Aufbewahrungsfrist löscht ein täglicher Auftrag die Mailboxen im Papierkorb endgültig. Bei der Wiederherstellung wird Ihr Mailbox-Limit pro Domain erneut geprüft. MCP-Agenten verwenden die Tools restore_mailbox und list_trashed_mailboxes; confirm_delete_intent ist jetzt wiederherstellbar und nicht unumkehrbar. Beim Löschen einer Domain oder eines Kontos werden die zugehörigen Mailboxen endgültig entfernt, ohne den Papierkorb zu verwenden.

Zweistufiges Löschen (Löschabsichten)

Das Löschen von Mailboxen und Domains gehört zu den folgenreichsten destruktiven Vorgängen der API. Dafür gilt ein zweistufiger Ablauf:

Schritt 1: Löschabsicht erstellen

POST /api/v1/mailboxes/{id}:delete-intent

Dadurch wird eine zeitlich begrenzte Absicht erstellt, die beschreibt, was gelöscht wird. Die Antwort enthält:

• Risikohinweise: Warnungen zu Weiterleitungsregeln, Aliasen oder aktiven Migrationen, die betroffen sein werden.
• Ablaufzeit: Die Absicht läuft nach 10 Minuten ab. Danach müssen Sie eine neue erstellen.
• Bestätigungs-URL: Die URL, die Sie für Schritt 2 aufrufen.

In diesem Schritt werden keine Daten gelöscht.

Schritt 2: Absicht bestätigen

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

Wenn der TrekMail-Papierkorb für Mailboxen aktiviert ist, verschiebt die Bestätigung die Mailbox nach Kürzlich gelöscht und gibt eine abgeschlossene Absicht mit status: "executed" zurück. Die Mailbox kann sieben Tage lang wiederhergestellt werden, sofern die Domain bei der Wiederherstellung genügend Platz dafür hat.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

Nach dem Wiederherstellungszeitraum entfernt die tägliche Bereinigung von TrekMail die Mailbox endgültig. Verwenden Sie vorher die Papierkorbliste oder den Wiederherstellungs-Endpunkt. Beim Löschen einer Domain oder eines Kontos kommt dieser Wiederherstellungspfad für Mailboxen nicht zum Einsatz.

Der Header X-Confirm-Delete: true ist als zusätzliche Sicherheitsprüfung in der Bestätigungsanfrage erforderlich.

Risikohinweise

Beim Erstellen einer Löschabsicht prüft die API Bedingungen, die darauf hindeuten könnten, dass Sie nicht fortfahren möchten:

Prüfen Sie diese Hinweise vor der Bestätigung. Die API blockiert die Bestätigung nicht aufgrund von Risikohinweisen. Sie dienen nur zur Information.

Ratenlimits für destruktive Vorgänge

Für destruktive Vorgänge gelten zusätzlich zum normalen API-Ratenlimit pro Minute zwei weitere Begrenzungen:

• Tageslimit pro Token: Jedes Token kann pro Tag nur eine begrenzte Anzahl von Löschabsichten bestätigen.
• Wartezeit zwischen Bestätigungen: Nach der Bestätigung eines Löschvorgangs gilt eine kurze Wartezeit, bevor die nächste Bestätigung angenommen wird.

Beide geben bei Auslösung 429 Too Many Requests mit einem Retry-After-Header zurück.

MCP-Sicherheitssteuerung für lokal gehostete Server

Wenn Sie den stdio-MCP-Server selbst betreiben, kann dessen Administrator TREKMAIL_ALLOW_DESTRUCTIVE=true verlangen, bevor Löschtools verfügbar sind. Dies ist eine lokale Sicherheitssteuerung und kein Funktionsschalter des TrekMail-Produkts. Gehostetes MCP verwendet die während OAuth genehmigten Berechtigungen.

Lesetools bleiben im Rahmen der gewährten Berechtigungen verfügbar. Prüfen Sie die Aufgabe und Berechtigungen des Agenten, bevor Sie Löschaktionen zulassen.

Idempotenz

Schreib-Endpunkte, die einen Idempotency-Key benötigen, weisen in der Endpunkttabelle und OpenAPI-Spezifikation darauf hin. Verwenden Sie für jeden logischen Vorgang einen neuen Schlüssel, bevor Sie eine Anfrage wiederholen:

Idempotency-Key: create-mailbox-alice-2024

• Derselbe Schlüssel mit demselben Body gibt die ursprüngliche Antwort zurück, ohne den Vorgang zu wiederholen.
• Derselbe Schlüssel mit einem anderen Body gibt 409 Conflict zurück.
• Verschiedene Tokens verwenden unabhängige Schlüsselräume.

Der MCP-Server erzeugt wiederholungssichere Idempotenzschlüssel für Tool-Aufrufe. Wiederholungsversuche führen einen bereits abgeschlossenen Vorgang daher nicht erneut aus.

Sicherheitsvorkehrungen für den Versand

Der E-Mail-Versand über den MCP-Server besitzt ein eigenes zweistufiges Sicherheitskonzept, das der Absicherung destruktiver Vorgänge ähnelt, aber zwei unabhängige Prüfungen verwendet:

Prüfung 1: Lokale Serversteuerung

Setzen Sie für einen lokal gehosteten MCP-Server TREKMAIL_ALLOW_SENDING=true, um das Tool send_message zuzulassen. Gehostetes MCP verwendet die während OAuth genehmigten Berechtigungen.

Prüfung 2: Bestätigung pro Aufruf

Auch bei aktivierter Umgebungssteuerung muss jeder Aufruf von send_message den Parameter confirm_send=true enthalten. Ohne ihn gibt das Tool einen Fehler zurück, der den Agenten zur Bestätigung auffordert.

Warum zwei Prüfungen?

Die lokale Steuerung wird einmal vom Administrator festgelegt, der den MCP-Server konfiguriert. Die Steuerung pro Aufruf zwingt den Agenten, sich bei jeder E-Mail aktiv für den Versand zu entscheiden. Keine der beiden Prüfungen reicht allein aus; beide müssen bestanden sein, bevor eine E-Mail den Server verlässt.

Dadurch werden versehentliche Sendungen durch Agenten verhindert, die verfügbare Tools erkunden, ohne deren Folgen zu verstehen. Ein Agent kann Nachrichten mit einem Nachrichten-Token frei auflisten und lesen, aber erst senden, wenn beide Sicherheitsprüfungen erfüllt sind.

Sicherheitsvorkehrungen für Migrationen

Die E-Mail-Migration über den MCP-Server besitzt eigene Sicherheitsvorkehrungen, ähnlich wie Versand und destruktive Vorgänge.

Lokale Serversteuerung für Migrationen

Setzen Sie für einen lokal gehosteten MCP-Server TREKMAIL_ALLOW_MIGRATION=true, um schreibende Migrationstools (start_migration, retry_migration, delete_migration) zuzulassen. Gehostetes MCP verwendet die während OAuth genehmigten Berechtigungen.

cancel_migration ist unabhängig von dieser Einstellung immer verfügbar. Es handelt sich um einen Sicherheitsvorgang, der jederzeit zugänglich sein muss, um eine außer Kontrolle geratene Migration zu stoppen.

Schreibgeschützte Migrationstools (list_migrations, get_migration) funktionieren ohne Sicherheitsprüfungen. test_migration_connection erfordert TREKMAIL_ALLOW_MIGRATION=true, weil es ausgehende IMAP-Verbindungen herstellt.

Bestätigung pro Migrationsaufruf

Jedes schreibende Migrationstool benötigt einen Bestätigungsparameter:

• start_migration erfordert confirm_start=true
• cancel_migration erfordert confirm_cancel=true
• retry_migration erfordert confirm_retry=true

Ohne den Bestätigungsparameter gibt das Tool einen Fehler zurück, der den Agenten zur Bestätigung auffordert.

Serverweites Parallelitätslimit

Die API erzwingt ein globales Limit für gleichzeitige Migrationen (Standard: 20). Wenn das Limit erreicht ist, geben neue Migrationsanfragen 503 mit migration_capacity_reached und retryable: true zurück. Dadurch werden Serverressourcen geschützt, wenn viele Konten gleichzeitig migriert werden.

Audit-Protokollierung

Jede verändernde API-Aktion wird im Audit-Protokoll aufgezeichnet, das im Dashboard unter KI-Agenten & API → Audit-Protokoll angezeigt wird. Zu den Ereignissen gehören:

• Token erstellt oder widerrufen: Wer ein Vorgangs-Token wann erstellt oder widerrufen hat.
• Nachrichten-Token erstellt oder widerrufen: Wer ein Nachrichten-Token erstellt oder widerrufen hat.
• Absicht erstellt: Für eine bestimmte Mailbox wurde eine Löschabsicht erstellt.
• Absicht bestätigt: Die Löschanfrage wurde angenommen.
• Löschen ausgeführt: Die Mailbox wurde nach Kürzlich gelöscht verschoben und ihr Wiederherstellungszeitraum begann.
• Absicht abgelaufen: Eine unbestätigte Absicht ist nach 10 Minuten abgelaufen.
• Mailbox erstellt: Über die API wurde eine neue Mailbox bereitgestellt.
• Einladung erstellt: Eine Einladung zur Einrichtung einer Mailbox wurde gesendet.
• Weiterleitung aktualisiert: Die Weiterleitungsregeln einer Mailbox wurden geändert.
• DNS-Neuprüfung ausgelöst: Für eine Domain wurde eine DNS-Überprüfung angefordert.
• Migration gestartet: Über die API wurde eine E-Mail-Migration gestartet.
• Migration abgebrochen: Eine laufende Migration wurde abgebrochen.
• Migration wiederholt: Eine fehlgeschlagene oder abgebrochene Migration wurde erneut versucht.
• Migration gelöscht: Ein Migrationsdatensatz wurde gelöscht.
• Nachricht gelesen: Nachrichten wurden über die Nachrichten-API aufgelistet oder gelesen.
• Nachricht gesendet: Eine E-Mail wurde über die Nachrichten-API gesendet.
• Nachrichtenversand fehlgeschlagen: Ein E-Mail-Sendeversuch ist fehlgeschlagen.
• Nachrichtenmarkierungen aktualisiert: Markierungen der Nachricht (gelesen/ungelesen, markiert) wurden geändert.
• Nachricht gelöscht: Eine Nachricht wurde aus einem Mailbox-Ordner gelöscht.
• Nachricht verschoben: Eine Nachricht wurde zwischen Ordnern verschoben.
• Domain erstellt: Eine Domain wurde über die API hinzugefügt.
• Domain gelöscht: Eine Domain wurde über die API entfernt.
• Ticket erstellt: Über die API wurde ein Support-Ticket eröffnet.
• Ticket beantwortet: In einem Ticket wurde eine Antwort veröffentlicht.
• Ticket geschlossen: Ein Ticket wurde geschlossen.
• SMTP konfiguriert: SMTP-Einstellungen wurden aktualisiert.
• SMTP-Verbindung gelöscht: Eine benutzerdefinierte SMTP-Verbindung wurde entfernt.
• SMTP-Test eingereiht: Ein SMTP-Verbindungstest wurde gestartet.
• Cloudflare-Token gelöscht: Ein gespeichertes Cloudflare-Token wurde über die API entfernt.

Alle Ereignisse der Nachrichten-API, darunter Lesen, Senden, Aktualisieren von Markierungen, Löschen und Verschieben, werden vollständig protokolliert. Audit-Datensätze werden 90 Tage lang aufbewahrt.

Jedes Ereignis erfasst das verwendete Token, die betroffene Ressource, die IP-Adresse und eine Anfrage-ID.

Filtern Sie das Audit-Protokoll nach Ereignistyp, Token oder Datumsbereich, um bestimmte Aktivitäten zu untersuchen.

Schnelle Lösungen

• Absicht vor der Bestätigung abgelaufen: Erstellen Sie eine neue Löschabsicht. Absichten laufen nach 10 Minuten ab.
• „Missing confirm header“: Fügen Sie den Header X-Confirm-Delete: true zur Bestätigungsanfrage hinzu.
• 429 bei der Löschbestätigung: Sie haben das Tageslimit oder die Wartezeit erreicht. Warten Sie den von Retry-After angegebenen Zeitraum.
• Ein selbst gehosteter MCP-Agent meldet, dass Löschtools deaktiviert sind: Sein lokaler Administrator kann TREKMAIL_ALLOW_DESTRUCTIVE=true in der Umgebung dieses MCP-Prozesses setzen.
• Ein selbst gehosteter MCP-Agent meldet „Sending is disabled“: Sein lokaler Administrator kann TREKMAIL_ALLOW_SENDING=true in der Umgebung dieses MCP-Prozesses setzen.
• Der MCP-Agent meldet „Send not confirmed“: Der Agent muss bei jedem Aufruf von send_message den Parameter confirm_send=true übergeben.
• Ein selbst gehosteter MCP-Agent meldet, dass Migrationstools deaktiviert sind: Sein lokaler Administrator kann TREKMAIL_ALLOW_MIGRATION=true in der Umgebung dieses MCP-Prozesses setzen.
• 503 „migration_capacity_reached“: Serverweit laufen zu viele Migrationen. Warten Sie einige Minuten und versuchen Sie es erneut.
• 409 „active migration running“: Brechen Sie die bestehende Migration ab oder warten Sie auf ihren Abschluss, bevor Sie eine neue starten.