Gestión de migraciones de correo mediante la API

La API de migración permite importar correo desde cualquier proveedor IMAP a un buzón de TrekMail mediante una integración o un agente. Puedes probar conexiones, iniciar importaciones, supervisar el progreso por carpeta, cancelar tareas en ejecución, reintentar las que fallen y eliminar registros antiguos.

Antes de empezar

• Necesitas un plan Starter o superior. El plan Nano no incluye la herramienta de migración.
• Los planes Pro y Agency permiten iniciar, cancelar, reintentar y eliminar migraciones mediante la API (migrations:read + migrations:write). Starter permite consultar las migraciones mediante la API y ejecutar otras nuevas desde el panel.
• Se puede ejecutar una migración por cuenta a la vez. Inicia otra cuando finalice la actual o cancela primero la que está en curso.

Permisos

Endpoints

Probar la conexión

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

Valida las credenciales IMAP y devuelve una lista de las carpetas de origen con su número de mensajes. Utiliza esta operación antes de iniciar una migración para comprobar que la conexión funciona y permitir que el usuario elija qué carpetas importar.

Cuerpo de la solicitud:

Respuesta (correcta):

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

Respuesta (error): 422 con el código de error connection_failed.

Enumerar migraciones

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

Devuelve una lista paginada de las tareas de migración de tu cuenta.

Parámetros de consulta:

Consultar una migración

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

Devuelve el estado detallado de la migración, incluido un desglose del progreso por carpeta.

Respuesta:

{
  "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 con qué frecuencia debes consultar las novedades: 5 segundos durante pending/validating/planning, 10 segundos durante processing y null para los estados finales.

source_email aparece oculto por seguridad (por ejemplo, j***e@gmail.com).

Iniciar una migración

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

Inicia una nueva migración de correo. Solo se puede ejecutar una migración por cuenta a la vez.

Cuerpo de la solicitud:

Respuesta: 201 con el recurso de la tarea de migración.

Respuestas de error:

Cancelar una migración

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

Cancela una migración en ejecución. La migración debe encontrarse en un estado activo (pending, validating, planning o processing).

Reintentar una migración

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

Reintenta una migración failed o cancelled. Restablece el progreso a 0 y vuelve a entrar en el proceso de validación.

Devuelve 409 si ya hay otra migración en ejecución en la cuenta.

Migraciones parciales

TrekMail puede intentar continuar una migración completada parcialmente cuando resulte seguro. Consulta el estado de la migración antes de realizar ninguna acción. Si ya no avanza, revisa las credenciales y los límites de la cuenta de origen y utiliza después el endpoint de reintento o la acción Continuar del panel. No des por sentado que una importación parcial terminará sin consultar su estado final.

Eliminar una migración

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

Elimina el registro de una migración. La migración no debe estar en ejecución (cancélala primero).

Devuelve 204 No Content cuando se completa correctamente.

Límites de frecuencia

Las operaciones de escritura de migraciones tienen un límite específico de 10 solicitudes por minuto y por token, independiente del límite de frecuencia estándar de la API.

Además, el servidor aplica un límite global de concurrencia (valor predeterminado: 20 migraciones simultáneas). Al alcanzar el límite, las nuevas solicitudes de migración devuelven 503 con migration_capacity_reached y retryable: true. Espera unos minutos y vuelve a intentarlo.

Eventos de auditoría

Todas las acciones de la API de migración se registran en el historial de auditoría:

• migration_started: se inició una nueva migración
• migration_cancelled: se canceló una migración en ejecución
• migration_retried: se reintentó una migración fallida o cancelada
• migration_deleted: se eliminó el registro de una migración

Herramientas MCP

Las mismas funciones de migración están disponibles mediante el servidor MCP, incluidas las acciones para probar, enumerar, iniciar, cancelar, reintentar, reanudar, actualizar contraseñas y eliminar migraciones individuales y masivas. Un administrador de un MCP alojado localmente puede exigir aprobación explícita para las operaciones de escritura de migraciones. Consulta Conectar agentes de IA (MCP) para obtener más información.

API de migración masiva

La API de migración masiva permite migrar muchas cuentas a la vez mediante una carga de datos con formato CSV. Consulta Migración masiva de correo para obtener la guía del usuario y Formato CSV para migración masiva para conocer el formato de los datos.

Endpoints

Solicitud de previsualización

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

La respuesta incluye filas clasificadas (valid, invalid_source_email, invalid_destination, etc.), límites del plan, una estimación de tiempo e información de almacenamiento.

Solicitud para iniciar un lote

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

Incluye los mismos campos que la previsualización, además de los siguientes:

Límites de concurrencia

El límite global del servidor (20 migraciones simultáneas) se comparte entre las migraciones individuales y masivas.

Herramientas MCP

Las herramientas MCP de migración masiva son preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration y update_bulk_migration_job_password. Un administrador de un MCP alojado localmente puede exigir aprobación explícita para las operaciones de escritura.

Soluciones rápidas

• 403 "insufficient_scope": tu token necesita migrations:read o migrations:write. Crea un token nuevo con los permisos correctos.
• 403 "token_scope_blocked_by_plan": los permisos de migración requieren un plan de pago (Starter o superior).
• 409 "active migration running": cancela la migración existente o espera a que finalice.
• 503 "migration_capacity_reached": el servidor ha alcanzado su capacidad. Vuelve a intentarlo dentro de unos minutos.
• 422 al probar la conexión: comprueba las credenciales IMAP, el nombre de host, el puerto y la configuración de seguridad.