E-Mail-Migrationen über die API verwalten

Mit der Migrations-API kannst du E-Mails von jedem IMAP-Anbieter über eine Integration oder einen Agenten in ein TrekMail-Postfach importieren. Du kannst Verbindungen testen, Importe starten, den Fortschritt für jeden Ordner überwachen, laufende Aufträge abbrechen, fehlgeschlagene Aufträge wiederholen und alte Datensätze bereinigen.

Vor dem Start

• Du benötigst mindestens den Starter-Tarif. Der Nano-Tarif enthält das Migrationswerkzeug nicht.
• Mit Pro und Agency kannst du Migrationen über die API starten, abbrechen, wiederholen und löschen (migrations:read + migrations:write). Starter kann Migrationen über die API lesen und neue Migrationen im Dashboard ausführen.
• Pro Konto kann jeweils eine Migration ausgeführt werden. Starte eine neue, nachdem die aktuelle beendet wurde, oder brich die aktuelle zuerst ab.

Berechtigungsbereiche

Endpunkte

Verbindung testen

POST /api/v1/migrations/test-connection
Scope: migrations:write

Validiert die IMAP-Zugangsdaten und gibt eine Liste der Quellordner mit der jeweiligen Nachrichtenanzahl zurück. Verwende dies vor dem Start einer Migration, um die Verbindung zu prüfen und den Benutzer die zu importierenden Ordner auswählen zu lassen.

Anfragetext:

Antwort (Erfolg):

{
  "success": true,
  "folders": {
    "INBOX": 1234,
    "Sent": 567,
    "Drafts": 12,
    "Work": 89
  }
}

Antwort (Fehler): 422 mit dem Fehlercode connection_failed.

Migrationen auflisten

GET /api/v1/migrations
Scope: migrations:read

Gibt eine paginierte Liste der Migrationsaufträge für dein Konto zurück.

Abfrageparameter:

Migration abrufen

GET /api/v1/migrations/{id}
Scope: migrations:read

Gibt den detaillierten Migrationsstatus einschließlich des Fortschritts für jeden Ordner zurück.

Antwort:

{
  "data": {
    "id": 5,
    "mailbox_id": 10,
    "mailbox_email": "support@acme.com",
    "provider": "gmail",
    "source_host": "imap.gmail.com",
    "source_email": "j***e@gmail.com",
    "status": "processing",
    "progress": 45,
    "total_messages": 1234,
    "imported_messages": 556,
    "failed_messages": 2,
    "skipped_duplicates": 12,
    "selected_folders": ["INBOX", "Sent"],
    "import_since": "2025-01-01",
    "skip_duplicates": true,
    "folders": [
      { "name": "INBOX", "status": "processing", "expected": 1000, "imported": 450, "failed": 2, "skipped": 10 },
      { "name": "Sent", "status": "pending", "expected": 234, "imported": 0, "failed": 0, "skipped": 0 }
    ],
    "error_message": null,
    "poll_hint_seconds": 10,
    "started_at": "2026-03-13T10:00:00+00:00",
    "finished_at": null,
    "created_at": "2026-03-13T09:59:50+00:00"
  }
}

poll_hint_seconds gibt an, wie oft du Aktualisierungen abrufen solltest: alle 5 Sekunden während pending/validating/planning, alle 10 Sekunden während processing und null bei endgültigen Zuständen.

source_email wird aus Sicherheitsgründen maskiert (z. B. j***e@gmail.com).

Migration starten

POST /api/v1/migrations
Scope: migrations:write

Startet eine neue E-Mail-Migration. Pro Konto kann jeweils nur eine Migration ausgeführt werden.

Anfragetext:

Antwort: 201 mit der Ressource des Migrationsauftrags.

Fehlerantworten:

Migration abbrechen

POST /api/v1/migrations/{id}:cancel
Scope: migrations:write

Bricht eine laufende Migration ab. Die Migration muss sich in einem aktiven Zustand befinden (pending, validating, planning oder processing).

Migration wiederholen

POST /api/v1/migrations/{id}:retry
Scope: migrations:write

Wiederholt eine Migration mit dem Status failed oder cancelled. Setzt den Fortschritt auf 0 zurück und startet die Validierung erneut.

Gibt 409 zurück, wenn bereits eine andere Migration im Konto ausgeführt wird.

Teilweise Migrationen

TrekMail versucht möglicherweise, eine teilweise abgeschlossene Migration fortzusetzen, wenn dies sicher möglich ist. Prüfe vor einer Aktion den Migrationsstatus. Wenn sie nicht mehr fortschreitet, prüfe die Zugangsdaten und Limits des Quellkontos und verwende anschließend den Endpunkt zum Wiederholen oder die Aktion Fortsetzen im Dashboard. Gehe nicht davon aus, dass ein teilweiser Import abgeschlossen wird, ohne seinen endgültigen Status zu prüfen.

Migration löschen

DELETE /api/v1/migrations/{id}
Scope: migrations:write

Löscht einen Migrationsdatensatz. Die Migration darf nicht ausgeführt werden (brich sie zuerst ab).

Gibt bei Erfolg 204 No Content zurück.

Ratenlimits

Für Schreibvorgänge bei Migrationen gilt ein eigenes Limit von 10 Anfragen pro Minute und Token, getrennt vom standardmäßigen API-Ratenlimit.

Zusätzlich erzwingt der Server ein globales Parallelitätslimit (Standard: 20 gleichzeitige Migrationen). Wenn das Limit erreicht ist, geben neue Migrationsanfragen 503 mit migration_capacity_reached und retryable: true zurück. Warte einige Minuten und versuche es erneut.

Audit-Ereignisse

Alle Aktionen der Migrations-API werden im Auditprotokoll aufgezeichnet:

• migration_started: Eine neue Migration wurde gestartet
• migration_cancelled: Eine laufende Migration wurde abgebrochen
• migration_retried: Eine fehlgeschlagene oder abgebrochene Migration wurde wiederholt
• migration_deleted: Ein Migrationsdatensatz wurde gelöscht

MCP-Werkzeuge

Dieselben Migrationsfunktionen stehen über den MCP-Server zur Verfügung. Dazu gehören Testen, Auflisten, Starten, Abbrechen, Wiederholen, Fortsetzen, Passwortaktualisierung und Löschen für einzelne und gebündelte Migrationen. Ein lokal betriebener MCP-Administrator kann eine ausdrückliche Genehmigung für Migrationsschreibvorgänge verlangen. Weitere Informationen findest du unter KI-Agenten verbinden (MCP).

API für gebündelte Migrationen

Mit der API für gebündelte Migrationen kannst du viele Konten gleichzeitig anhand einer CSV-artigen Datennutzlast migrieren. Im Benutzerhandbuch E-Mail-Massenmigration und unter CSV-Format für Massenmigrationen findest du weitere Informationen zum Datenformat.

Endpunkte

Vorschauanfrage

POST /api/v1/migrations/bulk/preview
Scope: migrations:write

Die Antwort enthält kategorisierte Zeilen (valid, invalid_source_email, invalid_destination usw.), Tariflimits, eine Zeitschätzung und Speicherinformationen.

Anfrage zum Starten eines Stapels

POST /api/v1/migrations/bulk
Scope: migrations:write

Enthält dieselben Felder wie die Vorschau sowie:

Parallelitätslimits

Das globale Serverlimit (20 gleichzeitige Migrationen) gilt gemeinsam für einzelne und gebündelte Migrationen.

MCP-Werkzeuge

Die MCP-Werkzeuge für gebündelte Migrationen sind preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration und update_bulk_migration_job_password. Ein lokal betriebener MCP-Administrator kann für Schreibaktionen eine ausdrückliche Genehmigung verlangen.

Schnelle Lösungen

• 403 "insufficient_scope": Dein Token benötigt migrations:read oder migrations:write. Erstelle ein neues Token mit den richtigen Bereichen.
• 403 "token_scope_blocked_by_plan": Migrationsbereiche erfordern einen kostenpflichtigen Tarif (Starter oder höher).
• 409 "active migration running": Brich die bestehende Migration ab oder warte auf ihren Abschluss.
• 503 "migration_capacity_reached": Der Server ist ausgelastet. Versuche es in einigen Minuten erneut.
• 422 beim Verbindungstest: Prüfe IMAP-Zugangsdaten, Hostname, Port und Sicherheitseinstellung.