Gestire le migrazioni email tramite API

L’API Migration consente di importare email da qualsiasi provider IMAP in una casella TrekMail tramite un’integrazione o un agente. Puoi testare le connessioni, avviare le importazioni, monitorare l’avanzamento per cartella, annullare i processi in esecuzione, riprovare quelli non riusciti e rimuovere i vecchi record.

Prima di iniziare

• È necessario un piano Starter o superiore. Il piano Nano non include lo strumento di migrazione.
• Con Pro e Agency è possibile avviare, annullare, riprovare ed eliminare le migrazioni tramite API (migrations:read + migrations:write). Con Starter è possibile leggere le migrazioni tramite API ed eseguirne di nuove dalla dashboard.
• Può essere eseguita una sola migrazione per account alla volta. Avviane una nuova dopo il completamento di quella corrente oppure annulla prima quella in corso.

Ambiti

Endpoint

Testare la connessione

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

Convalida le credenziali IMAP e restituisce un elenco delle cartelle di origine con il numero di messaggi. Usalo prima di avviare una migrazione per verificare che la connessione funzioni e consentire all’utente di scegliere le cartelle da importare.

Corpo della richiesta:

Risposta (operazione riuscita):

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

Risposta (errore): 422 con codice di errore connection_failed.

Elencare le migrazioni

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

Restituisce un elenco impaginato dei processi di migrazione per il tuo account.

Parametri di query:

Ottenere una migrazione

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

Restituisce lo stato dettagliato della migrazione, inclusa una suddivisione dell’avanzamento per cartella.

Risposta:

{
  "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 indica la frequenza con cui verificare gli aggiornamenti: 5 secondi durante pending/validating/planning, 10 secondi durante processing, null per gli stati terminali.

source_email è mascherato per motivi di sicurezza (ad esempio, j***e@gmail.com).

Avviare una migrazione

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

Avvia una nuova migrazione email. Può essere eseguita una sola migrazione per account alla volta.

Corpo della richiesta:

Risposta: 201 con la risorsa del processo di migrazione.

Risposte di errore:

Annullare una migrazione

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

Annulla una migrazione in esecuzione. La migrazione deve trovarsi in uno stato attivo (pending, validating, planning o processing).

Riprovare una migrazione

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

Riprova una migrazione failed o cancelled. Reimposta l’avanzamento su 0 e rientra nella pipeline di convalida.

Restituisce 409 se sull’account è già in esecuzione un’altra migrazione.

Migrazioni parziali

TrekMail può tentare di proseguire una migrazione completata in parte quando è sicuro farlo. Controlla lo stato della migrazione prima di intervenire. Se non avanza più, verifica le credenziali e i limiti dell’account di origine, quindi usa l’endpoint per riprovare o l’azione Continua della dashboard. Non presumere che un’importazione parziale venga completata senza verificarne lo stato finale.

Eliminare una migrazione

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

Elimina il record di una migrazione. La migrazione non deve essere in esecuzione (annullala prima).

In caso di esito positivo, restituisce 204 No Content.

Limiti di frequenza

Le operazioni di scrittura delle migrazioni hanno un limite di frequenza dedicato di 10 richieste al minuto per token, distinto dal limite di frequenza standard dell’API.

Inoltre, il server applica un limite di concorrenza globale (valore predefinito: 20 migrazioni simultanee). Quando viene raggiunto il limite, le nuove richieste di migrazione restituiscono 503 con migration_capacity_reached e retryable: true. Attendi qualche minuto e riprova.

Eventi di audit

Tutte le azioni dell’API per le migrazioni vengono registrate nel log di audit:

• migration_started: è stata avviata una nuova migrazione
• migration_cancelled: è stata annullata una migrazione in esecuzione
• migration_retried: è stata riprovata una migrazione non riuscita o annullata
• migration_deleted: è stato eliminato il record di una migrazione

Strumenti MCP

Le stesse funzionalità di migrazione sono disponibili tramite il server MCP, incluse le azioni di test, elenco, avvio, annullamento, nuovo tentativo, ripresa, aggiornamento della password ed eliminazione per migrazioni singole e collettive. Un amministratore MCP con hosting locale può richiedere l’approvazione esplicita per le operazioni di scrittura delle migrazioni. Per informazioni dettagliate, consulta Collegare gli agenti IA (MCP).

API per migrazioni collettive

L’API per migrazioni collettive consente di migrare più account contemporaneamente usando un payload di dati in stile CSV. Consulta Migrazione collettiva delle email per la guida utente e Formato CSV per migrazioni collettive per il formato dei dati.

Endpoint

Richiesta di anteprima

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

La risposta include righe suddivise per categoria (valid, invalid_source_email, invalid_destination, ecc.), limiti del piano, stima del tempo e informazioni sullo spazio di archiviazione.

Richiesta di avvio del gruppo

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

Gli stessi campi dell’anteprima, più:

Limiti di concorrenza

Il limite globale del server (20 migrazioni simultanee) è condiviso tra le migrazioni singole e quelle collettive.

Strumenti MCP

Gli strumenti MCP per le migrazioni collettive sono preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration e update_bulk_migration_job_password. Un amministratore MCP con hosting locale può richiedere l’approvazione esplicita per le azioni di scrittura.

Soluzioni rapide

• 403 "insufficient_scope": il token richiede migrations:read o migrations:write. Crea un nuovo token con gli ambiti corretti.
• 403 "token_scope_blocked_by_plan": gli ambiti di migrazione richiedono un piano a pagamento (Starter o superiore).
• 409 "active migration running": annulla la migrazione esistente o attendi che venga completata.
• 503 "migration_capacity_reached": il server ha raggiunto la capacità massima. Riprova tra qualche minuto.
• 422 durante test-connection: controlla le credenziali IMAP, il nome host, la porta e l’impostazione di sicurezza.