Gérer les migrations d’e-mails avec l’API

L’API de migration vous permet d’importer les e-mails de tout fournisseur IMAP dans une boîte TrekMail par l’intermédiaire d’une intégration ou d’un agent. Vous pouvez tester les connexions, lancer les imports, suivre la progression par dossier, annuler les tâches en cours, réessayer celles qui ont échoué et supprimer les anciens enregistrements.

Avant de commencer

• Vous devez disposer d’une offre Starter ou supérieure. L’offre Nano n’inclut pas l’outil de migration.
• Les offres Pro et Agency permettent de lancer, annuler, réessayer et supprimer des migrations par l’API (migrations:read + migrations:write). L’offre Starter permet de consulter les migrations par l’API et d’en exécuter de nouvelles depuis le tableau de bord.
• Une seule migration peut être exécutée par compte à la fois. Lancez-en une nouvelle après la fin de la migration actuelle ou annulez d’abord cette dernière.

Portées

Endpoints

Tester la connexion

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

Valide les identifiants IMAP et renvoie la liste des dossiers sources avec le nombre de messages. Utilisez cette opération avant de lancer une migration afin de vérifier la connexion et de laisser l’utilisateur choisir les dossiers à importer.

Corps de la requête :

Réponse (réussite) :

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

Réponse (échec) : 422 avec le code d’erreur connection_failed.

Répertorier les migrations

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

Renvoie une liste paginée des tâches de migration de votre compte.

Paramètres de requête :

Obtenir une migration

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

Renvoie l’état détaillé de la migration, avec la progression par dossier.

Réponse :

{
  "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 indique la fréquence d’interrogation des mises à jour : 5 secondes pendant pending/validating/planning, 10 secondes pendant processing et null pour les états finaux.

source_email est masqué pour des raisons de sécurité (par exemple j***e@gmail.com).

Lancer une migration

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

Lance une nouvelle migration d’e-mails. Une seule migration peut être exécutée par compte à la fois.

Corps de la requête :

Réponse : 201 avec la ressource de la tâche de migration.

Réponses d’erreur :

Annuler une migration

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

Annule une migration en cours. La migration doit se trouver dans un état actif (pending, validating, planning ou processing).

Réessayer une migration

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

Réessaie une migration failed ou cancelled. Réinitialise la progression à 0 et relance le processus de validation.

Renvoie 409 si une autre migration est déjà en cours sur le compte.

Migrations partielles

TrekMail peut tenter de poursuivre une migration partiellement terminée lorsqu’il est possible de le faire en toute sécurité. Vérifiez l’état de la migration avant d’agir. Si elle ne progresse plus, vérifiez les identifiants et les limites du compte source, puis utilisez l’endpoint de réessai ou l’action Continuer du tableau de bord. Ne supposez pas qu’une importation partielle se terminera sans vérifier son état final.

Supprimer une migration

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

Supprime l’enregistrement d’une migration. La migration ne doit pas être en cours (annulez-la d’abord).

Renvoie 204 No Content en cas de réussite.

Limites de débit

Les opérations d’écriture de migration disposent d’une limite dédiée de 10 requêtes par minute et par jeton, distincte de la limite standard de l’API.

Le serveur applique également une limite globale de concurrence (par défaut : 20 migrations simultanées). Lorsque cette limite est atteinte, les nouvelles requêtes de migration renvoient 503 avec migration_capacity_reached et retryable: true. Attendez quelques minutes, puis réessayez.

Événements d’audit

Toutes les actions de l’API de migration sont enregistrées dans le journal d’audit :

• migration_started : une nouvelle migration a été lancée
• migration_cancelled : une migration en cours a été annulée
• migration_retried : une migration échouée ou annulée a été relancée
• migration_deleted : l’enregistrement d’une migration a été supprimé

Outils MCP

Les mêmes fonctions de migration sont disponibles via le serveur MCP, notamment les actions de test, de consultation, de lancement, d’annulation, de nouvelle tentative, de reprise, de mise à jour du mot de passe et de suppression pour les migrations individuelles et groupées. Un administrateur MCP hébergé localement peut exiger une approbation explicite pour les écritures de migration. Consultez Connexion des agents d’IA (MCP) pour en savoir plus.

API de migration groupée

L’API de migration groupée vous permet de migrer plusieurs comptes à la fois au moyen d’une charge de données au format CSV. Consultez Migration groupée des e-mails pour le guide utilisateur et Format CSV de migration groupée pour le format des données.

Endpoints

Requête de prévisualisation

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

La réponse comprend les lignes classées (valid, invalid_source_email, invalid_destination, etc.), les limites de l’offre, une estimation de la durée et des informations de stockage.

Requête de lancement du lot

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

Mêmes champs que pour la prévisualisation, auxquels s’ajoutent :

Limites de concurrence

La limite globale du serveur (20 migrations simultanées) est partagée entre les migrations individuelles et groupées.

Outils MCP

Les outils MCP de migration groupée sont preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration et update_bulk_migration_job_password. Un administrateur MCP hébergé localement peut exiger une approbation explicite pour les actions d’écriture.

Correctifs rapides

• 403 "insufficient_scope" : votre jeton doit disposer de migrations:read ou migrations:write. Créez un nouveau jeton avec les portées appropriées.
• 403 "token_scope_blocked_by_plan" : les portées de migration nécessitent une offre payante (Starter ou supérieure).
• 409 "active migration running" : annulez la migration existante ou attendez qu’elle se termine.
• 503 "migration_capacity_reached" : le serveur a atteint sa capacité. Réessayez dans quelques minutes.
• 422 lors du test de connexion : vérifiez vos identifiants IMAP, le nom d’hôte, le port et le paramètre de sécurité.

Articles connexes

• Présentation de l’API
• Présentation de l’importation d’e-mails
• Portées de l’API et autorisations des offres
• Garde-fous et intentions de suppression
• Connexion des agents d’IA (MCP)