imapsync: parámetros que evitan perder correo

imapsync es la herramienta habitual para trasladar correo IMAP sin obligar a los usuarios a exportar PST, usar clientes de escritorio ni pasar un fin de semana haciendo pruebas. Hasta ahí, todo bien. El problema viene después. Un parámetro incorrecto, una mala correspondencia de carpetas o una suposición errónea sobre la autenticación pueden terminar en correo enviado ausente, carpetas duplicadas o mensajes nuevos borrados durante el cambio. Si primero necesitas conocer el proceso completo, consulta esta guía práctica de imapsync.

Por eso este artículo tiene un alcance deliberadamente preciso. Trata los parámetros que realmente cambian el resultado: tiempos de espera, conexiones persistentes, correspondencia de carpetas, límites de velocidad, eliminación de duplicados y opciones de borrado capaces de dañar un buzón activo. Si trasladas una cuenta, evitarás una repetición complicada. Si trasladas cincuenta, no tendrás que explicar a los clientes por qué su carpeta Enviados se dividió en tres copias.

En resumen, la configuración predeterminada de imapsync no es un plan de migración, sino un punto de partida. Las migraciones reales requieren pasadas por etapas, reglas explícitas para las carpetas y verificación antes de modificar el MX. Si TrekMail es el destino, el asistente de importación integrado en los planes de pago gestiona la recepción desde el panel, más rápido que administrar cada buzón con scripts de shell. La plataforma TrekMail comienza en $3.50/month, usa almacenamiento compartido en lugar de facturación por usuario y admite importación IMAP en el servidor desde Gmail, Outlook, Yahoo, iCloud e IMAP genérico.

Por qué imapsync falla cuando se confía en los valores predeterminados

imapsync copia correo entre almacenes IMAP activos, no entre archivos planos. Debe lidiar con distintas jerarquías de carpetas, particularidades de servidores, identificadores de mensajes y modelos de autenticación mientras la red intenta interrumpir la sesión. Por eso las ejecuciones seguras son más explícitas que los ejemplos pegados en foros.

Los fallos habituales son rutinarios y costosos:

1. Los mensajes grandes agotan el tiempo durante la carga.
2. Los nombres de carpetas se asignan mal y los usuarios creen que el correo desapareció.
3. Los proveedores limitan la tarea y empiezan a rechazar conexiones.
4. La autenticación moderna bloquea las contraseñas normales.
5. Los cambios de estado UID generan duplicados en pasadas posteriores.
6. `--delete2` borra correo reciente del destino después del cambio.

Si alguna migración fue «correcta salvo por Sent Items», no se debió al azar. Era previsible. El protocolo permitía el problema y la configuración predeterminada no te protegió.

Parámetros de conexión que mantienen activo imapsync

En buzones grandes, imapsync suele fallar porque la conexión termina antes de completarse la escritura del mensaje. Las operaciones APPEND largas, los servidores Exchange lentos y los cortafuegos con estado son responsables habituales. La solución es sencilla: ampliar el tiempo de espera, enviar señales de actividad y guardar el estado en caché para que las nuevas ejecuciones no comiencen desde cero.

Usa estos parámetros en la primera pasada real:

imapsync \
  --host1 imap.source.tld --user1 user@source.tld --passfile1 ./pass1 \
  --host2 imap.dest.tld   --user2 user@dest.tld   --passfile2 ./pass2 \
  --timeout 120 \
  --keepalive1 --keepalive2 \
  --usecache

Función de cada uno:

La caché importa más de lo que muchos creen. Las buenas migraciones son incrementales. Ejecutas una pasada masiva, corriges problemas de autenticación o correspondencia y realizas una o dos pasadas de recuperación. Con `--usecache`, imapsync dedica menos tiempo a releer ambos lados. Sin ella, cada repetición resulta más pesada de lo necesario.

Hay una salvedad. La documentación oficial advierte que, en algunos casos, `--usecache` no es seguro con combinaciones de filtros por tamaño y antigüedad. No acumules filtros aleatorios solo porque parezcan eficientes. Mantén sencilla la primera pasada.

Parámetros de carpetas que evitan el pánico por su desaparición

Cuando los usuarios dicen que imapsync perdió carpetas, el correo suele seguir allí. El verdadero problema es que el destino interpretó de otra forma la ruta del origen o una carpeta especial traducida nunca se asignó a la carpeta Enviados activa. imapsync necesita una traducción explícita cuando los proveedores no coinciden.

Las dos grandes trampas son los delimitadores de jerarquía y las carpetas especiales.

Ejemplo: algunos servidores usan puntos para anidar y otros, barras. Si el origen tiene INBOX.Clients.ProjectA y el destino espera INBOX/Clients/ProjectA, debes transformar la ruta durante la copia.

imapsync \
  --host1 old.example.com --user1 user@old.example.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@example.com --passfile2 ./pass2 \
  --regextrans2 's/\./\//g'

Después está el problema de Enviados. Cada proveedor usa un nombre distinto, y a los usuarios solo les importa que el correo aparezca en la vista activa correspondiente.

Si el buzón tiene carpetas especiales estándar, prueba primero --automap. En buzones cPanel desordenados, traducidos o antiguos, las transformaciones regex explícitas son más seguras. TrekMail también ofrece guías específicas para iniciar una importación en el panel y preparar el dominio mediante añadir un dominio, algo importante si preparas el destino antes del cambio.

Ejemplo conceptual: la carpeta no desapareció. Pasó de la carpeta Enviados esperada a un nombre de archivo sin procesar que el cliente no reconoce como «Enviados». Los mismos bytes, el lugar equivocado y, aun así, el mismo ticket de soporte.

Limita imapsync antes de que Google o Microsoft te limiten

imapsync puede parecer tráfico abusivo para los proveedores alojados. Las ráfagas rápidas de comandos APPEND y FETCH en muchos buzones activan controles, suspensiones temporales o aparentes errores de autenticación que en realidad son restricciones de capacidad. Avanzar despacio y de forma constante suele ser más rápido que quedar bloqueado.

Si trabajas con Google Workspace o Microsoft 365, controla el ritmo:

imapsync \
  --host1 imap.gmail.com --user1 user@source.tld --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@dest.tld --passfile2 ./pass2 \
  --maxbytespersecond 500000 \
  --maxmessagespersecond 2

Esto consigue dos cosas. Primero, reduce los picos de tráfico que activan las defensas del proveedor. Segundo, evita saturar entornos compartidos con ráfagas de mensajes pequeños. Importa en servidores cPanel antiguos y en entornos Office 365 ya cargados.

No trates las cifras como reglas sagradas. Son valores iniciales. El límite adecuado depende del tamaño del buzón, la concurrencia y la tolerancia del proveedor a trabajos IMAP prolongados. La regla operativa es sencilla: si una migración empieza bien y degenera en fallos intermitentes, reduce la velocidad antes de suponer que la contraseña es incorrecta.

Aquí también se vuelve evidente la diferencia entre el método antiguo y el nuevo.

Método antiguo: programar cada buzón a mano, ajustar los límites por ensayo y error y vigilar fallos a las 2 de la madrugada

Método nuevo: usar la importación integrada en el servidor de TrekMail para la recepción en planes de pago, mantener normalizado el destino y evitar precios por usuario. Las agencias con muchos dominios valoran menos terminar un buzón diez minutos antes que no pasar tres días clasificando reintentos. Si es tu caso, consulta esta guía sobre alojamiento de correo multidominio.

Parámetros de autenticación para 2025-2026: fallan las contraseñas, gana OAuth

En Google Workspace y Microsoft 365 ya no puedes dar por hecho que funcionará la autenticación IMAP con nombre de usuario y contraseña. Google indica que, desde el 1 de mayo de 2025, las cuentas Workspace dejaron de admitir «aplicaciones menos seguras» que solo usan esos datos. Las directrices de Exchange Online también remiten a OAuth para clientes IMAP.

Esto cambia la ejecución de imapsync. Si el origen admite XOAUTH2, necesitas un token de acceso en vez de la contraseña normal del usuario.

imapsync \
  --host1 outlook.office365.com \
  --user1 user@source.tld \
  --authmech1 XOAUTH2 \
  --oauthaccesstoken1 "ACCESS_TOKEN" \
  --host2 imap.trekmail.net \
  --user2 user@dest.tld --passfile2 ./pass2

En Google Workspace, las contraseñas de aplicación pueden ser una alternativa práctica para traslados puntuales cuando está habilitada la verificación en 2 pasos. En Microsoft 365, usa el flujo OAuth que Microsoft documenta para protocolos heredados. Si tu script todavía presupone que «contraseña correcta equivale a autenticación correcta», no refleja la realidad actual.

Fuentes autorizadas: guía de Google Workspace sobre aplicaciones menos seguras e instrucciones de Microsoft para OAuth con IMAP.

Parámetros de integridad que evitan omitir mensajes defectuosos

Algunos mensajes están dañados. Es normal en servidores antiguos. Cabeceras Message-ID ausentes, MIME mal formado, adjuntos gigantes y contenidos de cero bytes aparecen en migraciones reales. imapsync puede sortear parte del problema, pero debes indicarle cómo.

El primer parámetro útil es --addheader. La documentación oficial señala que añade una cabecera Message-Id generada cuando falta. Esto importa porque imapsync utiliza la identidad del mensaje para decidir qué existe ya.

El segundo es --maxsize. Si el buzón o la política de destino rechazan mensajes gigantes, no dejes que uno solo detenga toda la tarea.

imapsync \
  --host1 old.example.com --user1 user@old.example.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@example.com --passfile2 ./pass2 \
  --addheader \
  --maxsize 35000000

No se trata de fingir que esos mensajes no existen, sino de trasladar primero el 99% y después gestionar manualmente las excepciones mediante una lista controlada.

Si despliegas muchos buzones en paralelo, acompáñalo de un proceso de aprovisionamiento ordenado. Conviene leer la guía de TrekMail para crear cuentas de correo en masa, porque los problemas se agravan cuando la creación de buzones, la entrega de contraseñas y los cambios DNS se gestionan desde hojas de cálculo distintas.

El parámetro que causa la peor pérdida de datos: --delete2

`--delete2` indica a imapsync que elimine del destino los mensajes que no existen en el origen. Parece útil para crear un reflejo exacto. También es la forma más fácil de borrar correo nuevo perfectamente válido después de cambiar el MX si se ejecuta en el momento equivocado.

Esta es la secuencia del fallo:

1. Preparas el destino copiando el correo antiguo.
2. Cambias el MX al nuevo proveedor.
3. El correo reciente empieza a llegar al destino.
4. Vuelves a ejecutar imapsync con --delete2.
5. imapsync detecta correo exclusivo del destino y lo borra porque nunca existió en el origen.

No es un error. Es exactamente lo que le ordenaste.

Usa `--delete2` solo en un reflejo controlado anterior al cambio, cuando ambos lados aún dependen lógicamente del antiguo origen de verdad. Una vez cambiado el MX, exclúyelo del comando. Si el destino está activo y recibiendo, trátalo como autoridad para el correo nuevo.

Cuando los UID no son fiables, usa la comparación por cabeceras

Los UID de IMAP solo son fiables dentro del estado del servidor al que pertenecen. RFC 3501 define UIDVALIDITY precisamente porque las suposiciones sobre UID pueden fallar cuando cambia el estado. Si una carpeta se reconstruye o reindexa, imapsync puede creer que todos los mensajes son nuevos y duplicarlos en otra pasada.

En ese caso ayuda la comparación por cabeceras:

imapsync \
  --host1 old.example.com --user1 user@old.example.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@example.com --passfile2 ./pass2 \
  --useheader 'Message-Id'

Es más lento que confiar en los UID del servidor, pero también más seguro si el origen es inestable, se ha reconstruido o presenta incoherencias. La documentación oficial indica que los problemas de duplicación suelen resolverse cambiando a --useheader "Message-Id".

Para la verificación final, prefiero una pasada de prueba con correspondencia conservadora antes del cambio de DNS y otra incremental breve cuando los usuarios hayan dejado de escribir en el sistema antiguo.

Plantilla segura de comando imapsync

Una ejecución segura especifica conexión, correspondencia, exclusiones y modo de prueba. Empieza en seco, confirma el comportamiento de las carpetas y luego realiza la pasada real. No uses en producción un primer borrador del comando.

imapsync \
  --host1 imap.gmail.com --user1 user@source.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@dest.com --passfile2 ./pass2 \
  --timeout 120 --keepalive1 --keepalive2 \
  --usecache \
  --automap \
  --regextrans2 's/^\[Gmail\]\/Sent Mail/Sent Items/' \
  --exclude '^\[Gmail\]/All Mail' \
  --maxbytespersecond 500000 \
  --maxmessagespersecond 2 \
  --dry

Tres notas prácticas:

1. Usa primero --dry. Siempre.
2. Excluye en la primera pasada las carpetas de archivo enormes que no necesites.
3. Guarda el registro y mantén versionadas las líneas de comandos de cada lote.

Cuando el buzón llegue a TrekMail, los usuarios se conectan mediante IMAP estándar en imap.trekmail.net por el puerto 993. TrekMail solo admite IMAP, no POP3, una elección adecuada para sincronizar el estado entre dispositivos en lugar de convertir la bandeja de entrada en una lotería.

Conclusión: imapsync funciona si se opera como herramienta de migración

imapsync sigue siendo apropiado para muchos traslados. Pero debes tratarlo como software de migración con estado, no como un comando de copia simple. Configura tiempos de espera y conexiones persistentes. Asigna las carpetas deliberadamente. Reduce el ritmo cuando el proveedor imponga límites. Usa autenticación moderna. Mantén `--delete2` lejos del correo posterior al cambio. Si el estado UID no es fiable, fuerza la comparación por cabeceras.

Para gestionar con más facilidad la recepción, TrekMail proporciona un destino multidominio con precio fijo, almacenamiento compartido, importación integrada en el servidor en planes de pago y sin tarifas por cada nuevo buzón. Como referencia operativa después del traslado, continúa con este artículo sobre correo empresarial.