imapsync: guia operacional para migrar e-mails com segurança (2026)

Você está diante de um projeto de migração que causa apreensão. Precisa transferir os e-mails do Servidor A para o Servidor B sem perder uma única mensagem, sem destruir a estrutura de pastas e sem pagar uma "licença de migração" de $15 por usuário a um fornecedor terceirizado apenas para mover dados que já são seus.

O que você procura é o imapsync. Este guia explica exatamente como usá-lo sem causar estragos nas caixas de correio dos usuários.

O que é o imapsync (e o que ele não é)

O imapsync é um utilitário de linha de comando que sincroniza caixas de correio entre dois servidores IMAP. Ele atua como intermediário, conectando-se aos dois servidores ao mesmo tempo, lendo as mensagens na origem e acrescentando-as ao destino. O utilitário acompanha o estado da operação, lida com interrupções e preserva a estrutura de pastas, os sinalizadores e o conteúdo das mensagens.

Ele não é uma ferramenta de backup nem um servidor de retransmissão SMTP. Não transfere seu Google Agenda, seus contatos do Outlook nem suas regras de transporte do Exchange. Ele se comunica por IMAP e somente por IMAP. Se o servidor de origem estiver isolado por firewall ou offline, o imapsync não conseguirá acessá-lo. Ponto final.

O que o tornou o padrão do setor para transferências entre caixas de correio é a camada de preservação de estado. Uma migração bem-sucedida não se resume a mover texto. É preciso preservar três elementos:

• Conteúdo: o corpo da mensagem no padrão RFC 822, os anexos, a codificação MIME, enfim, tudo que está dentro do envelope.
• Metadados: os sinalizadores. \Seen (lida), \Answered (respondida), \Flagged (marcada). Se eles não forem transferidos, todos os usuários pensarão que receberam 4,000 e-mails novos e não lidos no primeiro dia.
• Estrutura: a hierarquia de pastas. INBOX/Clients/ProjectA deve aparecer de forma idêntica no novo servidor, e não ser reduzida a uma pasta literalmente chamada INBOX.Clients.ProjectA, com pontos no nome.

O imapsync preserva os três elementos, desde que seja configurado corretamente. Essa é a parte difícil e é para isso que este guia serve.

Limitações incontornáveis: ele não conhece por conta própria os limites de uso do Gmail nem as restrições de API da Microsoft. Execute-o em velocidade máxima e seu IP poderá ser bloqueado. Ele também não envia os dados ativamente. Se você precisa levar os dados a algum lugar, deve puxá-los. Além disso, ele não exclui conteúdo no destino por padrão. Trata-se de um recurso de segurança que também pode causar problemas se você não estiver atento. Falaremos mais sobre isso na Fase 6.

Para conhecer melhor o protocolo em si, consulte nosso guia sobre como configurar e-mail no seu domínio.

Fase 1: levantamento minucioso, não pule esta etapa

Amadores começam a copiar. Profissionais primeiro auditam o ambiente. Se você não souber o que está transferindo, a migração dará errado, e isso acontecerá às 2h da manhã de um domingo, quando será tarde demais para corrigir.

1. Identifique os pesos-pesados

Você tem um usuário com uma caixa de correio de 45GB. Talvez seja o CEO, talvez seja quem controla o alias sales@ desde 2011. Se tentar migrá-lo no mesmo lote dos usuários com 500MB, o lote ficará paralisado e você olhará para um terminal congelado sem saber quanto falta.

Primeiro, faça uma varredura preliminar:

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

Esse comando detalha o tamanho por pasta sem alterar uma única mensagem. Qualquer caixa de correio acima de 10GB exige tratamento específico: tempos limite maiores, uma janela de execução exclusiva e toda a sua atenção.

2. O problema dos dados esquecidos

Toda empresa tem contas zumbis. Ex-funcionários cujos e-mails ainda são encaminhados para algum lugar. "Contas de serviço" que, na realidade, são caixas compartilhadas de uma impressora ou de uma integração antiga com o CRM. Se elas ficarem de fora do inventário, seus dados serão abandonados quando você mudar o DNS.

Compare a lista de usuários da origem com os usuários realmente ativos. Se bob@company.com saiu há três anos, decida agora: você vai migrar a caixa dele ou arquivá-la em uma exportação EML? Se não decidir antes da virada, terá de decidir sob pressão no pior momento possível. Consulte nosso guia de gerenciamento de e-mail de clientes para ver um modelo completo de inventário prévio.

3. A verdade está na quantidade de itens

Nunca confie no tamanho em gigabytes. O Servidor A de origem pode informar que a caixa tem 10GB. O Servidor B de destino pode contabilizar exatamente os mesmos dados como 11GB. Isso não é um erro. Servidores diferentes calculam o armazenamento de maneiras distintas. O Exchange inclui a pasta Recoverable Items, conhecida como "Dumpster". O Gmail elimina duplicatas entre marcadores.

A métrica importante é a quantidade de itens. Se a origem tem 14,200 mensagens e o destino tem 14,200 mensagens, a tarefa está concluída. Uma variação inferior a 10% no número de bytes é normal e esperada. Acima de 10%, investigue antes de aprovar a migração.

Fase 2: o fluxo seguro de migração

O maior erro em qualquer migração é a abordagem de virar tudo de uma vez: transferir todo o conteúdo na sexta à noite e torcer para terminar até segunda de manhã. Com 50GB de e-mails e um limite de 500KB/s, a conta não fecha. Na segunda-feira, o serviço estará indisponível e você terá de explicar ao CEO por que a caixa de entrada está vazia.

A abordagem profissional é uma migração em etapas. Você faz o trabalho pesado enquanto os usuários ainda estão no sistema antigo e transfere apenas uma pequena diferença final no momento da virada.

Etapa 1: a simulação

Antes de transferir um único byte, verifique se a conexão funciona. Use --dry com --justfolders. Essa combinação simula a execução e mostra a estrutura de pastas sem 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

Observe duas coisas: a autenticação funcionou e como são os nomes das pastas? Se houver [Gmail]/Sent Mail na origem, você precisará mapeá-la para Sent Items no destino. Não deixe para descobrir isso durante a virada real.

Etapa 2: a sincronização principal (pré-carga)

Execute-a de 1 a 2 semanas antes da virada, enquanto os usuários ainda trabalham no sistema antigo. O objetivo é retirar de 90 a 95% dos dados do caminho crítico.

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 é indispensável. A opção salva o estado da migração localmente. Cada execução seguinte consulta esse cache e processa apenas as alterações. Assim, o programa não reavalia todas as mensagens desde o início. Sem o cache, toda execução faz uma varredura completa.

--maxsize 25000000 ignora, na primeira passagem, mensagens maiores que 25MB. Anexos grandes são os principais responsáveis por tempos limite e quedas de conexão. Você os transferirá em uma execução específica, com tempos limite ampliados.

Etapa 3: a sincronização incremental

Alguns dias antes da virada, execute novamente. O imapsync lê o cache, identifica que 10,000 e-mails já estão no destino, ignora esses itens e copia apenas as 50 a 100 mensagens novas recebidas desde a sincronização principal. Essa execução deve terminar em minutos, não em horas.

Etapa 4: a virada

Este é o momento decisivo. Siga esta ordem:

1. Reduza o TTL do DNS: 48 horas antes da virada, defina o TTL do registro MX como 300 segundos. Se você esperar até o último minuto, alguns resolvedores manterão o MX antigo no cache por até 24 horas, e os e-mails chegarão ao servidor antigo mesmo depois da virada.
2. Altere os registros MX: aponte-os para o novo provedor.
3. Aguarde 60 minutos para a propagação se estabilizar nos principais resolvedores.
4. Execute a sincronização incremental final: uma última passagem do imapsync captura as mensagens que chegaram ao servidor antigo durante a janela de propagação.

Para ver instruções detalhadas sobre a janela de DNS e o que acompanhar durante a propagação, consulte nosso guia sobre como configurar e-mail no seu domínio.

Fase 3: sinalizadores, pastas e a armadilha dos itens enviados

Servidores IMAP falam dialetos diferentes. Se você não fizer a tradução entre eles, os usuários encontrarão uma caixa de correio estruturalmente danificada, e culparão você com razão.

O problema do delimitador

Essa é a falha técnica mais comum sobre a qual ninguém fala antes de enfrentá-la.

Servidores IMAP diferentes usam caracteres distintos para separar os níveis da hierarquia de pastas:

• O Dovecot normalmente usa ponto: INBOX.Clients.ProjectA
• O Exchange/Outlook usa barra: INBOX/Clients/ProjectA
• Alguns servidores não usam separador e dependem do comando IMAP NAMESPACE

Se você migrar sem verificar, o imapsync poderá criar no destino uma pasta literalmente chamada INBOX.Clients.ProjectA. Será uma única pasta sem hierarquia, com pontos no nome, e não uma estrutura aninhada de três níveis. Para os usuários, a estrutura de pastas parecerá ter explodido.

A solução é --regextrans2, que reescreve os caminhos das pastas durante a operação por meio de expressões regulares. Sempre teste a criação de pastas com --dry em uma única conta de teste antes de executar um lote de 100 usuários.

O caos dos itens enviados

Cada servidor dá um nome diferente à pasta de itens enviados. Isso não é um pequeno inconveniente. Se você ignorar o problema, a experiência do usuário será péssima.

Sem esse mapeamento, o usuário termina com duas pastas de itens enviados: a pasta ativa Sent Items e uma nova pasta fantasma chamada Sent Mail, que contém todo o histórico. Ele vai perceber e não ficará satisfeito.

Faça o mapeamento explicitamente:

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

Isso diz ao imapsync: "Se a pasta de origem começar com [Gmail]/Sent Mail, renomeie-a para Sent Items no destino." Primeiro, execute o mapa completo de pastas com --dry para confirmar que todas as regras funcionam corretamente antes de efetivar a operação.

A armadilha da pasta "All Mail" do Gmail

O Gmail tem uma pasta chamada [Gmail]/All Mail. Ela contém uma cópia de cada e-mail, independentemente do marcador. É a visão interna que reúne tudo no Gmail, exposta como uma pasta IMAP.

Se você migrar All Mail e Inbox e Sent Mail, duplicará cada e-mail duas ou três vezes no destino. Uma caixa de 10GB vira uma caixa de 30GB. Todas as mensagens aparecem várias vezes. É um desastre.

Sempre exclua essa pasta:

--exclude "All Mail"

Exclua também [Gmail]/Spam e [Gmail]/Trash, a menos que haja um motivo específico para transferi-las. Ninguém quer migrar spam antigo.

Fase 4: ajuste de desempenho e limitação de velocidade

Você não pode bombardear o Google ou a Microsoft com dados. A infraestrutura dessas empresas trata uma conexão IMAP de alto volume exatamente como um ataque de negação de serviço, pois, da perspectiva delas, a aparência é a mesma.

As consequências do excesso de uso

Ultrapasse os limites de uso, normalmente cerca de 1 mensagem por segundo ou 500MB por hora no Gmail, e o servidor começará a responder com HTTP 429, NO [OVERQUOTA] ou simplesmente erros BAD. Se insistir, a conta poderá ficar bloqueada por até 24 horas. Esse é um chamado para o suporte que você não quer abrir.

Opções 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 mensagem por segundo parece extremamente lento. E é. Mas o ritmo é constante, e um processo constante chega ao fim. Uma execução agressiva bloqueada após 3 horas nunca termina.

Observação para MSPs: se você realiza migrações paralelas para vários clientes, não as execute simultaneamente no mesmo servidor de origem. Escalone os horários de início. Cada fluxo paralelo precisa de seu próprio limite de tráfego.

Se você estiver migrando para o TrekMail, nossa ingestão por IMAP foi projetada para muitas conexões simultâneas. Em geral, é possível usar mais velocidade no destino do que na origem quando ela é o Google ou a Microsoft.

Fase 5: autenticação, o obstáculo da autenticação moderna

Acabou a época de colocar password123 em um arquivo de texto simples. Tanto o Google quanto a Microsoft descontinuaram a autenticação básica para IMAP. Se você tentar usar as credenciais normais, receberá um erro de autenticação e passará uma hora tentando entender o que fez de errado.

Senhas de app (opção para PMEs)

Na maioria das migrações de um único domínio, as senhas de app são o caminho mais rápido. São sequências de 16 caracteres que ignoram a 2FA e funcionam com clientes IMAP antigos:

1. Entre na conta de origem (Gmail, Workspace etc.)
2. Ative a autenticação de 2 fatores se ainda não estiver ativa (ela é necessária para gerar senhas de app)
3. Acesse Configurações de segurança → Senhas de app
4. Gere uma senha para "Mail" em "Outro dispositivo"
5. Use essa sequência como senha na opção --passfile do imapsync

Armazene-a em um arquivo com chmod 600, e não na linha de comando. Credenciais no histórico do Bash são um incidente à espera de acontecer.

OAuth2 (opção para MSPs e grandes empresas)

Se você é um MSP migrando 500 usuários, não pode gerar manualmente 500 senhas de app. Você precisa do OAuth2. Essa opção é mais complexa, mas é a única viável em grande escala:

1. Registre um aplicativo no tenant de origem (Azure AD para Microsoft, Google Cloud Console para Google)
2. Conceda a ele acesso completo às caixas de correio do tenant (é necessária a aprovação de um Administrador Global)
3. Gere um Refresh Token por usuário ou use uma conta de serviço para representar o usuário
4. Passe o token ao imapsync por meio de --oauthaccesstoken1

Se você configurar incorretamente as permissões do aplicativo no Azure AD ou no GCP, o acesso será negado em todas as caixas ou, pior, você concederá sem querer permissões mais amplas que as necessárias. Leia com atenção os escopos de permissão antes de clicar em "Grant admin consent".

Para ver na prática como conduzir migrações em escala, consulte nosso guia sobre gerenciamento de e-mail de clientes.

Fase 6: falhas comuns e recuperação

Até um plano perfeito encontra problemas. Veja como entender o que deu errado e corrigir sem começar tudo de novo.

1. O problema do UIDVALIDITY (o pior cenário)

Cada pasta IMAP tem um identificador exclusivo chamado UIDVALIDITY. É assim que o imapsync acompanha quais mensagens já foram copiadas. Se uma pasta no servidor de origem for excluída e recriada, ou se o índice do servidor for corrompido e reconstruído, esse ID mudará.

Sintoma: o imapsync encontra um novo UIDVALIDITY, presume que se trata de uma pasta totalmente nova e baixa tudo outra vez. Agora você tem cópias duplicadas de todas as mensagens dessa pasta. Em grande escala, são milhares de duplicatas em centenas de caixas de correio.

Correção: exclua os arquivos locais de cache no diretório temporário e execute novamente com --useheader:

--useheader

Isso força o imapsync a comparar o cabeçalho Message-ID de cada e-mail, que é imutável e exclusivo, em vez de depender do UID da pasta. É mais lento, mas evita duplicatas. Use sempre que suspeitar que o índice do servidor de origem foi alterado.

2. Mensagens corrompidas e com tamanho zero

Servidores antigos acumulam mensagens "fantasmas": cabeçalhos sem corpo ou arquivos com exatamente 0 byte. Em geral, são resultado de uma importação malsucedida, de uma entrega interrompida ou de um servidor muito antigo, com anos de manutenção adiada.

Sintoma: o imapsync tenta buscar uma mensagem, o servidor fica travado por 120 segundos e depois encerra a conexão. Isso se repete indefinidamente na mesma mensagem.

Correção:

--minbytes 10

Isso instrui o imapsync a ignorar mensagens menores que 10 bytes. Um e-mail real nunca tem menos de 10 bytes. Na prática, é um filtro para ignorar arquivos vazios, seguro para qualquer migração.

3. O problema das exclusões zumbis

Você executou a sincronização principal na segunda-feira. Na terça, o usuário excluiu 50 e-mails da origem. Na quarta, você executa a sincronização incremental.

Por padrão, o imapsync apenas adiciona e-mails. Ele não exclui do destino o que foi apagado na origem. Isso é intencional e correto para a maioria dos casos. Porém, significa que esses 50 e-mails excluídos reaparecerão na nova caixa. Os usuários relatarão "e-mails fantasmas" ou "e-mails que excluí e voltaram".

A solução é --delete2, mas use-a com extrema cautela:

--delete2

Isso instrui o imapsync: se uma mensagem não estiver na origem, exclua-a do destino.

Use essa opção apenas durante a pré-carga, antes da mudança do MX. Se você executá-la após a virada, as novas mensagens que chegaram ao destino, pois o MX já aponta para ele, serão excluídas porque não existem na origem antiga. Você perderá e-mails. Não use --delete2 após a virada.

4. Quedas de conexão com anexos grandes

Um anexo PDF de 40MB às vezes paralisa conexões IMAP com tempo limite curto. O servidor envia a mensagem, ocorre uma oscilação na rede, a conexão cai em 95%, e o imapsync registra um erro e segue adiante. O destino fica com uma mensagem incompleta.

Correção: aumente --timeout para 300 segundos nas passagens de anexos grandes. Considere usar --maxsize 25000000 para ignorá-los na sincronização principal e, depois, execute uma passagem exclusiva para anexos grandes, com limitação mais flexível e tempos limite maiores.

Verificação: como comprovar que funcionou

O script terminou. O terminal informa que concluiu. Como saber se os e-mails do CEO não desapareceram em uma rota nula qualquer?

1. Leia o bloco de resumo

O imapsync apresenta um resumo no fim de cada execução. Três números importam:

• Transferred: deve ser 0 na sincronização incremental final. Se não for zero, ainda há mensagens que não foram transferidas.
• Skipped: deve corresponder à quantidade total na origem ou ser maior. Essas mensagens já estão no destino.
• Errors: deve ser 0. Qualquer quantidade de erros diferente de zero precisa ser investigada antes de considerar o trabalho concluído.

2. A verificação por amostragem

Entre na nova caixa com um cliente IMAP recém-configurado. Não use um cliente que tenha armazenamento local em cache, pois isso anularia a verificação. Confira:

• Itens enviados: os e-mails enviados ao longo dos anos estão presentes e nas pastas corretas?
• Uma subpasta profundamente aninhada: a hierarquia está correta?
• O e-mail mais recente: é o mesmo exibido na origem?
• Uma mensagem sinalizada ou marcada com estrela: o atributo \Flagged foi transferido?

3. A busca investigativa

Um usuário informa que um e-mail sumiu. Antes de dizer "deve ter sido perdido", consulte o log:

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

O log registra o destino de cada mensagem: Transferred, Skipped (já estava no destino) ou Error, com o código específico. Se houver um Error, você saberá exatamente qual mensagem, pasta e código de erro causaram o problema. Esse é o ponto de partida da recuperação, não um palpite.

4. A auditoria da quantidade de itens

Para uma verificação final de coerência, consulte diretamente os dois 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"

Compare a quantidade de itens na origem e no destino. Os valores devem ficar dentro de uma diferença de 1 a 2%, considerando as pastas de spam excluídas e a eliminação de duplicatas da pasta All Mail do Gmail. Se a diferença for maior, investigue o log de erros antes de aprovar a migração.

A alternativa: dispensar o terminal

Escrevemos este guia porque acreditamos em transparência. O imapsync é a ferramenta certa para profissionais que querem controle total e não se importam em lidar com dependências do Perl, registros de aplicativos OAuth2 e análise minuciosa de logs.

Para muitos profissionais, no entanto, seja um fundador migrando seu primeiro domínio ou uma agência transferindo 200 contas de clientes, o tempo necessário para configurar tudo isso supera a economia com software.

A ferramenta de migração integrada do TrekMail funciona no servidor. Nada de arrastar pastas no Outlook por três horas ou enfrentar um inferno de dependências do Perl. Você informa a origem (Gmail, cPanel ou qualquer servidor IMAP padrão), insere as credenciais e o servidor cuida da transferência. O andamento fica visível no painel.

O modelo de preços também é diferente do que você provavelmente conhece. Não há cobrança por usuário. Os planos de preço fixo a partir de $3.50 por mês são voltados a até 100 usuários em 50 domínios, com armazenamento compartilhado entre todos eles. Assim, um executivo com 40GB de anexos não obriga você a fazer upgrade para todos, pois o armazenamento é compartilhado em toda a conta.

Para comparar o que está incluído em cada plano, consulte os preços do TrekMail. Para acompanhar especificamente o uso da ferramenta de migração, consulte o guia Como iniciar uma migração na nossa documentação.

Seja executando seu próprio script com imapsync ou usando nossa plataforma, o objetivo é o mesmo: transferir seus e-mails sem perder dados, sem transtornos e sem pagar um pedágio por usuário.

Se você quer parar de pagar tarifas por usuário e prefere deixar a migração por nossa conta, experimente o TrekMail grátis. São 14 dias de teste, sem exigir cartão.