imapsync: guía operativa para migrar correo con seguridad (2026)

Estás ante un proyecto de migración que impone respeto. Necesitas trasladar el correo del servidor A al servidor B sin perder un solo mensaje, sin destruir la estructura de carpetas y sin pagar una «licencia de migración» de $15/usuario a un proveedor externo solo para mover datos que ya son tuyos.

La herramienta que buscas es imapsync. Esta guía explica cómo usarla sin poner en riesgo los buzones de tus usuarios.

Qué es imapsync y qué no es

imapsync es una utilidad de línea de comandos que sincroniza buzones entre dos servidores IMAP. Actúa como intermediario: se conecta a ambos servidores a la vez, lee los mensajes del origen y los añade al destino. Registra el estado, gestiona interrupciones y conserva la estructura de carpetas, las marcas y el contenido de los mensajes.

No es una herramienta de copia de seguridad ni un relé SMTP. No interviene en Google Calendar, los contactos de Outlook ni las reglas de transporte de Exchange. Habla IMAP y solo IMAP. Si el servidor de origen está tras un cortafuegos o fuera de servicio, imapsync no puede acceder a él. Así de simple.

Lo que la convierte en el estándar del sector para trasladar buzones es su capa de conservación del estado. Una migración correcta no consiste solo en mover texto, sino en conservar tres elementos:

• Contenido: el cuerpo del mensaje RFC 822, los adjuntos, la codificación MIME y todo lo que contiene el sobre.
• Metadatos: las marcas. \Seen (leído), \Answered (respondido), \Flagged (destacado). Si no se trasladan, cada usuario creerá que tiene 4,000 mensajes nuevos sin leer el primer día.
• Estructura: la jerarquía de carpetas. INBOX/Clients/ProjectA debe verse igual en el servidor nuevo, no quedar aplanada en una carpeta llamada literalmente INBOX.Clients.ProjectA, con puntos en el nombre.

imapsync se ocupa de los tres elementos, siempre que se configure bien. Esa es la parte difícil y el objetivo de esta guía.

Sus límites estrictos: no conoce por sí sola los límites de velocidad de Gmail ni la limitación de las API de Microsoft. Si la ejecutas a máxima velocidad, pueden bloquear tu IP. Tampoco envía datos por iniciativa propia: si quieres llevarlos a otro lugar, tienes que extraerlos. Además, de forma predeterminada no elimina nada en el destino. Es una medida de seguridad que también puede causarte problemas si no prestas atención, como veremos en la Fase 6.

Para conocer mejor el protocolo, consulta nuestra guía sobre cómo configurar correo en tu dominio.

Fase 1: análisis forense previo. No te lo saltes

Los principiantes empiezan copiando; los profesionales auditan primero el entorno. Si no sabes qué vas a mover, la migración fallará, y lo hará a las 2 de la madrugada de un domingo, cuando ya sea demasiado tarde para corregirla.

1. Identifica los buzones gigantes

Tienes un usuario con un buzón de 45GB. Quizá sea el CEO o quien conserve el alias sales@ desde 2011. Si intentas migrarlo en el mismo lote que los usuarios con 500MB, el proceso se atascará y te quedarás mirando un terminal inmóvil sin saber cuánto ha avanzado.

Ejecuta antes un análisis previo:

imapsync \
  --host1 imap.source.com --user1 user@source.com --passfile1 /secret/pass1 \
  --host2 imap.dest.com --user2 user@dest.com --passfile2 /secret/pass2 \
  --dry --justfoldersizes

Obtendrás un desglose por carpeta sin tocar un solo mensaje. Todo buzón de más de 10GB requiere un tratamiento específico: tiempos de espera más largos, una ventana de ejecución propia y toda tu atención.

2. El problema de los datos oscuros

Toda empresa tiene cuentas zombi: exempleados cuyo correo todavía se reenvía a alguna parte y «cuentas de servicio» que en realidad son bandejas compartidas de una impresora o una integración antigua con el CRM. Si no aparecen en el inventario, esos datos quedarán aislados cuando cambies el DNS.

Compara la lista de usuarios del origen con los usuarios realmente activos. Si bob@company.com se marchó hace tres años, decide ahora si vas a migrar su buzón o archivarlo como exportación EML. Si no lo decides antes del cambio, tendrás que hacerlo bajo presión en el peor momento. Nuestra guía de gestión del correo de clientes incluye una plantilla completa de inventario previo.

3. La verdad está en el número de elementos

No confíes nunca en el tamaño en gigabytes. El servidor de origen A puede indicar que un buzón ocupa 10GB y el servidor de destino B, que los mismos datos ocupan 11GB. No es un error: los servidores calculan el almacenamiento de manera distinta. Exchange incluye la carpeta Recoverable Items, conocida como «Dumpster», y Gmail deduplica mensajes entre etiquetas.

La métrica importante es el número de elementos. Si hay 14,200 mensajes en el origen y 14,200 mensajes en el destino, la migración está completa. Una variación de bytes inferior al 10% es normal y esperable. Si supera el 10%, investiga antes de aprobar el resultado.

Fase 2: flujo de migración seguro

El mayor error en cualquier migración es el enfoque «Big Bang»: trasladarlo todo el viernes por la noche y esperar que termine el lunes por la mañana. Con 50GB de correo y un límite de 500KB/s, las cuentas no salen. El lunes el servicio seguirá caído y tendrás que explicar al CEO por qué su bandeja está vacía.

El enfoque profesional es una migración por etapas. Realizas el trabajo pesado mientras los usuarios siguen en el sistema antiguo y ejecutas un último delta mínimo al hacer el cambio.

Paso 1: simulación

Antes de mover un solo byte, verifica que puedes conectarte. Combina --dry con --justfolders. Así simulas la ejecución y ves la estructura de carpetas sin copiar nada.

imapsync \
  --host1 imap.gmail.com --user1 user@source.com --passfile1 /secret/pass1 \
  --host2 imap.trekmail.net --user2 user@dest.com --passfile2 /secret/pass2 \
  --dry --justfolders

Comprueba dos cosas: si la autenticación funciona y qué aspecto tienen los nombres de las carpetas. Si ves [Gmail]/Sent Mail en el origen, tendrás que asignarla a Sent Items en el destino. No esperes al cambio en producción para descubrirlo.

Paso 2: sincronización masiva previa

Ejecútala 1 a 2 semanas antes del cambio, mientras los usuarios aún trabajan en el sistema antiguo. El objetivo es sacar el 90 al 95% de los datos de la ruta crítica.

imapsync \
  --host1 imap.source.com --user1 user@source.com --passfile1 /secret/pass1 \
  --host2 imap.dest.com --user2 user@dest.com --passfile2 /secret/pass2 \
  --usecache --skipsize --maxsize 25000000

--usecache es imprescindible. Guarda localmente el estado de la migración. Cada ejecución posterior compara los datos con esta caché y procesa solo los cambios, sin volver a examinar cada mensaje desde cero. Sin esta opción, cada ejecución supone un análisis completo.

--maxsize 25000000 omite en la primera pasada los mensajes de más de 25MB. Los adjuntos grandes causan la mayoría de los tiempos de espera agotados y cortes de conexión. Los recuperarás en una ejecución específica con tiempos de espera más amplios.

Paso 3: sincronización delta

Unos días antes del cambio, vuelve a ejecutar el proceso. imapsync lee la caché, detecta que ya hay 10,000 mensajes en el destino, los omite y copia únicamente los 50 a 100 mensajes nuevos que llegaron después de la sincronización masiva. Esta ejecución debería tardar minutos, no horas.

Paso 4: cambio de servidor

Ha llegado el momento. Sigue este orden:

1. Reduce el TTL del DNS: 48 horas antes del cambio, establece en 300 segundos el TTL del registro MX. Si esperas al último momento, algunos resolutores DNS conservarán el MX antiguo hasta 24 horas y el correo llegará al servidor anterior cuando ya hayas realizado el cambio.
2. Cambia los registros MX: oriéntalos al nuevo proveedor.
3. Espera 60 minutos para que la propagación se estabilice en los principales resolutores DNS.
4. Ejecuta el delta final: una última pasada de imapsync recoge los mensajes que hayan llegado al servidor antiguo durante la propagación.

Nuestra guía sobre cómo configurar correo en tu dominio explica en detalle la ventana de DNS y qué vigilar durante la propagación.

Fase 3: marcas, carpetas y la trampa de Enviados

Los servidores IMAP hablan dialectos distintos. Si no traduces entre ellos, los usuarios se encontrarán un buzón con la estructura rota y te culparán, con razón.

El problema del delimitador

Es el fallo técnico más habitual del que nadie habla hasta que le ocurre.

Los servidores IMAP usan caracteres distintos para separar los niveles de la jerarquía de carpetas:

• Dovecot suele usar un punto: INBOX.Clients.ProjectA
• Exchange/Outlook usa una barra: INBOX/Clients/ProjectA
• Algunos servidores no usan ningún separador y dependen del comando IMAP NAMESPACE

Si migras sin comprobarlo, imapsync puede crear en el destino una carpeta llamada literalmente INBOX.Clients.ProjectA: una única carpeta plana con puntos en el nombre, no una jerarquía anidada de tres niveles. La estructura de carpetas de cada usuario parecerá haber explotado.

La solución es --regextrans2, que reescribe sobre la marcha las rutas mediante expresiones regulares. Prueba siempre la creación de carpetas con --dry en una sola cuenta de prueba antes de ejecutar un lote de 100 usuarios.

El caos de los elementos enviados

Cada servidor llama de forma distinta a la carpeta de enviados. No es una molestia menor: si la ignoras, arruinará la experiencia del usuario.

Si no asignas estas carpetas, el usuario acabará con dos carpetas de enviados: la carpeta activa Sent Items y una nueva carpeta fantasma llamada Sent Mail que contiene todo su historial. Lo notará y no le gustará.

Asígnalas expresamente:

--regextrans2 's/^\[Gmail\]\/Sent Mail/Sent Items/'

Esto indica a imapsync: «Si la carpeta de origen empieza por [Gmail]/Sent Mail, llámala Sent Items en el destino». Ejecuta primero todo el mapa de carpetas con --dry para confirmar que cada asignación se aplica correctamente.

La trampa de All Mail en Gmail

Gmail tiene una carpeta llamada [Gmail]/All Mail. Contiene una copia de cada mensaje, sea cual sea su etiqueta. Es la vista interna global de Gmail expuesta como carpeta IMAP.

Si migras All Mail y Inbox y Sent Mail, duplicarás cada mensaje dos o tres veces en el destino. Un buzón de 10GB pasará a ocupar 30GB y cada mensaje aparecerá varias veces. Será un desastre.

Exclúyela siempre:

--exclude "All Mail"

Excluye también [Gmail]/Spam y [Gmail]/Trash, salvo que tengas un motivo concreto para trasladarlas. Nadie quiere migrar el spam antiguo.

Fase 4: optimización del rendimiento y limitación de velocidad

No puedes lanzar datos contra Google o Microsoft sin control. Su infraestructura trata una conexión IMAP de gran volumen igual que un ataque de denegación de servicio porque, desde su perspectiva, tienen el mismo aspecto.

El bloqueo por exceso de tráfico

Si superas los límites de velocidad, normalmente alrededor de 1 mensaje por segundo o 500MB por hora en Gmail, el servidor empieza a devolver HTTP 429, NO [OVERQUOTA] o simples errores BAD. Si insistes, la cuenta queda bloqueada durante 24 horas. No querrás tener que hacer esa llamada a soporte.

Opciones de ajuste

--maxmessagespersecond 1     # Hard speed limit: 1 email per second
--maxbytespersecond 500000   # Bandwidth cap: 500KB/s
--timeout 120                # Network timeout in seconds (default is often too short for big attachments)
--reconnectretry1 3          # Retry on source connection drops
--reconnectretry2 3          # Retry on destination connection drops

1 mensaje por segundo parece desesperadamente lento. Lo es. Pero es constante, y lo constante termina. Una ejecución agresiva bloqueada en la hora 3 no termina nunca.

Nota para MSP: si ejecutas migraciones paralelas para varios clientes, no las lances simultáneamente contra el mismo servidor de origen. Escalona las horas de inicio. Cada flujo paralelo necesita su propio margen de limitación.

Si migras a TrekMail, nuestro sistema de ingesta IMAP gestiona bien las conexiones muy concurrentes. En el destino puedes avanzar más deprisa que en un origen de Google o Microsoft.

Fase 5: autenticación. El obstáculo de la autenticación moderna

Se acabaron los días de guardar password123 en un archivo de texto sin cifrar. Google y Microsoft han retirado la autenticación básica para IMAP. Si pruebas tus credenciales habituales, recibirás un error de autenticación y perderás una hora preguntándote qué has hecho mal.

Contraseñas de aplicación (opción para pymes)

Para la mayoría de las migraciones de un solo dominio, las contraseñas de aplicación son la vía más rápida. Son cadenas de 16 caracteres que evitan la 2FA y funcionan con clientes IMAP antiguos:

1. Inicia sesión en la cuenta de origen (Gmail, Workspace, etc.)
2. Activa la autenticación de 2 factores si aún no está habilitada, ya que es necesaria para generar contraseñas de aplicación
3. Ve a los ajustes de Seguridad → Contraseñas de aplicaciones
4. Genera una contraseña para «Correo» en «Otro dispositivo»
5. Usa esa cadena como contraseña en --passfile de imapsync

Guárdala en un archivo con chmod 600, no en la línea de comandos. Dejar credenciales en el historial de Bash es un problema en ciernes.

OAuth2 (opción para MSP y empresas)

Si eres un MSP que migra 500 usuarios, no puedes generar manualmente 500 contraseñas de aplicación. Necesitas OAuth2. Esta vía es más compleja, pero es la única opción realista a gran escala:

1. Registra una aplicación en el tenant de origen (Azure AD para Microsoft o Google Cloud Console para Google)
2. Concédele acceso completo a los buzones de todo el tenant, con la aprobación obligatoria del administrador global
3. Genera un Refresh Token por usuario o usa una cuenta de servicio para suplantar la identidad del usuario
4. Pasa el token a imapsync mediante --oauthaccesstoken1

Si configuras mal los permisos de la aplicación en Azure AD o GCP, obtendrás acceso denegado en todos los buzones o, peor aún, concederás sin querer permisos más amplios de lo previsto. Lee detenidamente los ámbitos de permisos antes de pulsar «Conceder consentimiento de administrador».

Para ver un enfoque práctico de la migración a escala, consulta nuestra guía sobre gestión del correo de clientes.

Fase 6: fallos habituales y recuperación

Incluso un plan perfecto encuentra problemas. Así puedes interpretar qué ha fallado y corregirlo sin empezar de nuevo.

1. El problema de UIDVALIDITY (la peor situación)

Cada carpeta IMAP tiene un identificador único llamado UIDVALIDITY. imapsync lo utiliza para saber qué mensajes se han copiado. Si una carpeta del servidor de origen se elimina y se vuelve a crear, o si el índice del servidor se corrompe y se reconstruye, este identificador cambia.

Síntoma: imapsync detecta un UIDVALIDITY nuevo, presupone que se trata de una carpeta completamente nueva y vuelve a descargarlo todo. Ahora tienes duplicados de cada mensaje de esa carpeta. A gran escala, son miles de duplicados repartidos por cientos de buzones.

Solución: elimina los archivos de caché locales del directorio temporal y vuelve a ejecutar el proceso con --useheader:

--useheader

Esta opción obliga a imapsync a comparar la cabecera Message-ID de cada mensaje, que es inmutable y única, en vez de depender del UID de la carpeta. Es más lento, pero evita duplicados. Úsala siempre que sospeches que se ha modificado el índice del servidor de origen.

2. Mensajes dañados o de cero bytes

Los servidores antiguos acumulan mensajes «fantasma»: cabeceras sin cuerpo o archivos de exactamente 0 bytes. Suelen deberse a una importación fallida, una entrega interrumpida o un servidor muy antiguo con años de mantenimiento aplazado.

Síntoma: imapsync intenta recuperar un mensaje, el servidor queda bloqueado durante 120 segundos y después interrumpe la conexión. El ciclo se repite indefinidamente con el mismo mensaje.

Solución:

--minbytes 10

Esta opción indica a imapsync que omita cualquier mensaje de menos de 10 bytes. Un mensaje real nunca ocupa menos de 10 bytes. En la práctica es un filtro para «omitir archivos vacíos» y se puede usar con seguridad en cualquier migración.

3. El problema de los mensajes eliminados que reaparecen

Ejecutaste la sincronización masiva el lunes. El martes, el usuario eliminó 50 mensajes del origen. El miércoles ejecutas el delta.

De forma predeterminada, imapsync solo añade correo: no elimina en el destino lo que se borró en el origen. Es una decisión deliberada y correcta para la mayoría de los casos, pero implica que esos 50 mensajes eliminados reaparecerán en el buzón nuevo. Los usuarios informarán de «mensajes fantasma» o «mensajes que había borrado y han vuelto».

La solución es --delete2, pero úsala con extrema cautela:

--delete2

Esta opción indica a imapsync que elimine del destino cualquier mensaje que no esté en el origen.

Úsala solo durante la etapa previa, antes de cambiar el MX. Si la ejecutas después, el correo nuevo que haya llegado al destino, porque el MX ya apunta allí, se eliminará al no existir en el origen antiguo. Perderás mensajes. No uses --delete2 después del cambio.

4. Cortes de conexión con adjuntos grandes

Un PDF adjunto de 40MB puede bloquear conexiones IMAP con un tiempo de espera corto. El servidor envía el mensaje, la red sufre una interrupción, la conexión se corta al 95% e imapsync registra un error y continúa, dejando un mensaje incompleto en el destino.

Solución: aumenta --timeout a 300 segundos en las pasadas de adjuntos grandes. También puedes usar --maxsize 25000000 para omitirlos durante la sincronización masiva y ejecutar después una pasada específica con límites más flexibles y tiempos de espera mayores.

Verificación: cómo demostrar que ha funcionado

El script ha terminado y el terminal dice que está listo. ¿Cómo sabes que los mensajes del CEO no han desaparecido en una ruta nula?

1. Lee el bloque de resumen

imapsync muestra un resumen al final de cada ejecución. Estas son las tres cifras importantes:

• Transferred: debería ser 0 en el delta final. Si no es cero, todavía hay mensajes que no han llegado.
• Skipped: debería coincidir con el número total de mensajes del origen o superarlo. Son mensajes que ya están en el destino.
• Errors: debería ser 0. Cualquier cifra de errores distinta de cero exige investigar antes de dar el trabajo por terminado.

2. Comprobación puntual

Inicia sesión en el buzón nuevo con un cliente IMAP limpio, no con uno que tenga datos locales en caché, pues eso invalidaría la prueba. Comprueba:

• Sent Items: ¿aparecen años de correo enviado y están bien anidados?
• Una subcarpeta profunda: ¿es correcta la jerarquía?
• El mensaje más reciente: ¿es el mismo que aparece en el origen?
• Un mensaje marcado o destacado: ¿se ha conservado el atributo \Flagged?

3. Búsqueda forense

Un usuario informa de que falta un mensaje. Antes de decir «debe de haberse perdido», consulta el registro:

grep -i "bob@sender.com" /var/log/imapsync/user@source.com.log

El registro recoge el destino de cada mensaje: Transferred, Skipped (ya estaba en el destino) o Error con su código concreto. Si aparece Error, sabrás exactamente qué mensaje, carpeta y código lo causaron. Ese es el punto de partida para recuperarlo, no las conjeturas.

4. Auditoría del número de elementos

Como última comprobación, consulta directamente ambos servidores:

# On source (example for Dovecot)
doveadm mailbox status -u user@source.com messages '*'

# Or use imapsync's own count
imapsync ... --dry --justfoldersizes 2>&1 | grep "Messages"

Compara el número de elementos del origen y el destino. La diferencia debería estar dentro del 1 al 2%, teniendo en cuenta las carpetas de spam excluidas y la deduplicación de All Mail de Gmail. Si es mayor, revisa el registro de errores antes de aprobar el resultado.

La alternativa: prescindir del terminal

Hemos escrito esta guía porque creemos en la transparencia. imapsync es la herramienta adecuada para operadores que quieren control absoluto y no les importa lidiar con dependencias de Perl, registros de aplicaciones OAuth2 y análisis forense de logs.

Sin embargo, para muchos operadores, tanto un fundador que traslada su primer dominio como una agencia que migra 200 puestos de clientes, el tiempo necesario para configurarlo todo cuesta más que lo que se ahorra en software.

La herramienta de migración integrada de TrekMail funciona en el servidor: no hay que arrastrar carpetas en Outlook durante tres horas ni pelear con dependencias de Perl. Indicas el origen (Gmail, cPanel o cualquier servidor IMAP estándar), introduces las credenciales y el servidor se ocupa de la transferencia. Puedes seguir el progreso en el panel.

El modelo de precios también es distinto de lo habitual. No se cobra por usuario. Los planes de tarifa plana empiezan en $3.50/mes y cubren hasta 100 usuarios en 50 dominios, con almacenamiento compartido entre todos. Ese directivo con 40GB de adjuntos no obliga a subir de plan a todos, porque el almacenamiento se comparte en toda la cuenta.

Consulta los precios de TrekMail para comparar lo que incluye cada nivel. Para ver el proceso específico de la herramienta paso a paso, consulta la guía Iniciar una migración en nuestra documentación.

Tanto si escribes tus propios scripts con imapsync como si usas nuestra plataforma, el objetivo es el mismo: trasladar el correo sin perder datos, sin sobresaltos y sin pagar un peaje por puesto.

Si quieres dejar de pagar por usuario y prefieres que gestionemos la migración, prueba TrekMail gratis: 14 días, sin tarjeta.