E-mailmigraties beheren via de API

Met de Migration API kun je via een integratie of agent e-mail van elke IMAP-provider importeren in een TrekMail-mailbox. Je kunt verbindingen testen, imports starten, de voortgang per map volgen, actieve taken annuleren, mislukte taken opnieuw proberen en oude records opruimen.

Voordat je begint

• Je hebt een Starter-abonnement of hoger nodig. Het Nano-abonnement bevat de migratietool niet.
• Met Pro en Agency kun je migraties via de API starten, annuleren, opnieuw proberen en verwijderen (migrations:read + migrations:write). Met Starter kun je migraties via de API lezen en nieuwe migraties vanuit het dashboard uitvoeren.
• Er kan per account één migratie tegelijk worden uitgevoerd. Start een nieuwe nadat de huidige is voltooid of annuleer eerst de huidige migratie.

Scopes

Endpoints

Verbinding testen

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

Valideert IMAP-inloggegevens en retourneert een lijst met bronmappen en het aantal berichten. Gebruik dit voordat je een migratie start om te controleren of de verbinding werkt en de gebruiker te laten kiezen welke mappen moeten worden geïmporteerd.

Aanvraagbody:

Reactie (geslaagd):

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

Reactie (mislukt): 422 met foutcode connection_failed.

Migraties weergeven

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

Retourneert een gepagineerde lijst met migratietaken voor je account.

Queryparameters:

Migratie ophalen

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

Retourneert de gedetailleerde migratiestatus, inclusief een uitsplitsing van de voortgang per map.

Reactie:

{
  "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 geeft aan hoe vaak je op updates moet controleren: 5 seconden tijdens pending/validating/planning, 10 seconden tijdens processing en null voor eindstatussen.

source_email wordt om veiligheidsredenen gemaskeerd (bijvoorbeeld j***e@gmail.com).

Migratie starten

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

Start een nieuwe e-mailmigratie. Er kan per account één migratie tegelijk worden uitgevoerd.

Aanvraagbody:

Reactie: 201 met de resource van de migratietaak.

Foutreacties:

Migratie annuleren

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

Annuleert een actieve migratie. De migratie moet een actieve status hebben (pending, validating, planning of processing).

Migratie opnieuw proberen

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

Probeert een failed of cancelled migratie opnieuw. Zet de voortgang terug op 0 en gaat opnieuw de validatiepijplijn in.

Retourneert 409 als er al een andere migratie op het account wordt uitgevoerd.

Gedeeltelijke migraties

TrekMail kan proberen een gedeeltelijk voltooide migratie voort te zetten wanneer dit veilig is. Controleer de migratiestatus voordat je actie onderneemt. Als de migratie niet meer vordert, controleer je de inloggegevens en limieten van het bronaccount. Gebruik daarna het endpoint om opnieuw te proberen of de actie Doorgaan in het dashboard. Ga er niet van uit dat een gedeeltelijke import wordt voltooid zonder de eindstatus te controleren.

Migratie verwijderen

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

Verwijdert een migratierecord. De migratie mag niet actief zijn (annuleer deze eerst).

Retourneert bij succes 204 No Content.

Frequentielimieten

Schrijfbewerkingen voor migraties hebben een eigen frequentielimiet van 10 verzoeken per minuut per token, los van de standaard frequentielimiet van de API.

Daarnaast hanteert de server een globale gelijktijdigheidslimiet (standaard: 20 gelijktijdige migraties). Wanneer de limiet is bereikt, retourneren nieuwe migratieverzoeken 503 met migration_capacity_reached en retryable: true. Wacht een paar minuten en probeer het opnieuw.

Auditgebeurtenissen

Alle acties van de migratie-API worden vastgelegd in het auditlogboek:

• migration_started: er is een nieuwe migratie gestart
• migration_cancelled: een actieve migratie is geannuleerd
• migration_retried: een mislukte of geannuleerde migratie is opnieuw geprobeerd
• migration_deleted: een migratierecord is verwijderd

MCP-tools

Dezelfde migratiemogelijkheden zijn beschikbaar via de MCP-server, waaronder acties om enkele en bulkmigraties te testen, weer te geven, te starten, te annuleren, opnieuw te proberen, te hervatten, het wachtwoord bij te werken en te verwijderen. Een lokaal gehoste MCP-beheerder kan expliciete goedkeuring vereisen voor schrijfbewerkingen voor migraties. Zie AI-agenten verbinden (MCP) voor meer informatie.

API voor bulkmigraties

Met de API voor bulkmigraties kun je veel accounts tegelijk migreren via een gegevenspayload in CSV-stijl. Zie Bulk-e-mailmigratie voor de gebruikershandleiding en CSV-indeling voor bulkmigraties voor de gegevensindeling.

Endpoints

Aanvraag voor voorvertoning

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

De reactie bevat gecategoriseerde rijen (valid, invalid_source_email, invalid_destination, enzovoort), abonnementslimieten, een tijdsschatting en opslaginformatie.

Aanvraag om batch te starten

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

Dezelfde velden als voor de voorvertoning, plus:

Gelijktijdigheidslimieten

De globale serverlimiet (20 gelijktijdige migraties) wordt gedeeld door afzonderlijke migraties en bulkmigraties.

MCP-tools

De MCP-tools voor bulkmigratie zijn preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration en update_bulk_migration_job_password. Een lokaal gehoste MCP-beheerder kan expliciete goedkeuring vereisen voor schrijfacties.

Snelle oplossingen

• 403 "insufficient_scope": je token heeft migrations:read of migrations:write nodig. Maak een nieuw token met de juiste scopes.
• 403 "token_scope_blocked_by_plan": voor migratiescopes is een betaald abonnement nodig (Starter of hoger).
• 409 "active migration running": annuleer de bestaande migratie of wacht totdat deze is voltooid.
• 503 "migration_capacity_reached": de server heeft de maximale capaciteit bereikt. Probeer het over een paar minuten opnieuw.
• 422 bij test-connection: controleer je IMAP-inloggegevens, hostnaam, poort en beveiligingsinstelling.