Ferramenta imapsync: parâmetros que evitam a perda de e-mails

imapsync é a ferramenta escolhida por quem precisa mover e-mails por IMAP sem obrigar usuários a exportar PSTs, usar aplicativos de desktop ou passar o fim de semana tentando adivinhar o que ocorreu. Até aí, tudo bem. O problema vem depois. Um parâmetro errado, um mapeamento ruim ou uma suposição incorreta sobre autenticação pode terminar a migração sem as mensagens enviadas, com pastas duplicadas ou com e-mails novos apagados durante a virada. Se você precisa primeiro entender o processo completo, leia este guia operacional sobre imapsync.

Por isso, este artigo é deliberadamente específico. Ele trata dos parâmetros do imapsync que realmente mudam o resultado: tempos limite, keepalives, mapeamento de pastas, controle de tráfego, eliminação de duplicatas e opções de exclusão que podem danificar uma caixa ativa. Ao mover uma conta, você evita uma repetição confusa. Ao mover cinquenta, evita explicar aos clientes por que a pasta de enviados foi dividida em três cópias.

Em resumo: as configurações padrão do imapsync não são um plano de migração. São um ponto de partida. Migrações reais exigem etapas, regras explícitas para pastas e verificação antes de alterar o MX. Se o destino for a TrekMail, o assistente de importação integrado aos planos pagos pode cuidar do recebimento no painel, o que costuma ser mais prático do que gerenciar cada caixa manualmente com scripts de shell. Conforme a página de preços, a plataforma TrekMail começa em $3.50/month, usa armazenamento compartilhado em vez de cobrança por usuário e aceita importação IMAP no servidor para Gmail, Outlook, Yahoo, iCloud e servidores IMAP genéricos.

Por que o imapsync falha quando o operador confia nos padrões

O imapsync copia mensagens entre repositórios IMAP ativos, não entre arquivos simples. Ele precisa lidar com hierarquias de pastas, peculiaridades dos servidores, identificadores de mensagens e modelos de autenticação diferentes enquanto a rede tenta interromper a sessão. Por isso, execuções seguras sempre são mais explícitas que exemplos copiados de fóruns.

Os problemas comuns são previsíveis e caros:

1. Mensagens grandes excedem o tempo limite no envio.
2. Pastas são mapeadas incorretamente e parecem ter desaparecido.
3. Provedores limitam a tarefa e recusam conexões.
4. A autenticação moderna rejeita senhas simples.
5. Mudanças no estado dos UIDs geram duplicatas em passagens posteriores.
6. `--delete2` apaga mensagens novas no destino depois da virada.

Se uma migração já ficou “quase certa, exceto por Sent Items”, não foi algo aleatório. Era previsível. O protocolo permitiu o problema e as configurações padrão não o impediram.

Parâmetros de conexão que mantêm o imapsync ativo

Em caixas grandes, o imapsync normalmente falha porque a conexão termina antes da gravação da mensagem. Operações APPEND longas, servidores Exchange lentos e firewalls com estado são causas frequentes. A solução é aumentar a tolerância de tempo, enviar keepalives e armazenar o estado para que novas execuções não comecem do zero.

Use estes parâmetros na primeira passagem importante:

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

O que cada um faz:

O cache é mais importante do que parece. Boas migrações são incrementais. Você executa uma passagem em massa, corrige autenticação ou mapeamento e faz uma ou duas passagens complementares. Com `--usecache`, o imapsync relê menos dados nos dois lados. Sem ele, cada repetição é mais pesada do que precisa.

Há uma ressalva. A documentação oficial alerta que, em alguns casos, `--usecache` não é seguro quando combinado a filtros de tamanho e idade. Não empilhe filtros aleatórios só porque parecem eficientes. Mantenha a primeira passagem simples.

Parâmetros de mapeamento que evitam o pânico da “pasta ausente”

Quando usuários dizem que o imapsync perdeu pastas, muitas vezes as mensagens ainda existem. O destino apenas interpretou o caminho de outra maneira, ou uma pasta especial localizada não foi associada à pasta de enviados ativa. O imapsync precisa de tradução explícita quando os provedores discordam.

As duas grandes armadilhas são os separadores de hierarquia e as pastas especiais.

Por exemplo, alguns servidores usam pontos para aninhar pastas e outros usam barras. Se a origem contém INBOX.Clients.ProjectA e o destino espera INBOX/Clients/ProjectA, reescreva o caminho durante a cópia.

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'

Há também o problema da pasta de enviados. Os provedores usam nomes diferentes, mas o usuário só quer ver suas mensagens na pasta ativa correta.

Se a caixa tiver pastas especiais padrão, tente primeiro --automap. Para caixas cPanel antigas, localizadas ou desorganizadas, transformações regex explícitas são mais seguras. A TrekMail também oferece guias específicos para iniciar uma importação no painel e preparar o domínio em adicionar um domínio, algo relevante ao preparar o destino antes da virada.

Exemplo conceitual: a pasta não desapareceu. Ela saiu da pasta de enviados esperada e foi para uma pasta com nome bruto de arquivo, que o aplicativo não trata como “Enviados”. Os bytes são os mesmos, mas estão no lugar errado. O chamado de suporte será o mesmo.

Limite o imapsync antes que Google ou Microsoft limitem você

Provedores hospedados podem interpretar o imapsync como tráfego abusivo. Rajadas de comandos APPEND e FETCH em muitas caixas acionam controles, suspensões temporárias ou erros que parecem de autenticação, mas são de capacidade. Um ritmo constante costuma ser mais rápido do que sofrer um bloqueio.

Ao usar Google Workspace ou Microsoft 365, controle o 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

Isso reduz picos que acionam defesas dos provedores e evita sobrecarregar ambientes compartilhados com rajadas de mensagens pequenas. É importante em servidores cPanel antigos e em ambientes Office 365 já bastante ocupados.

Não trate esses números como regras absolutas. São valores iniciais. O limite adequado depende do tamanho, da simultaneidade e da tolerância do provedor a tarefas IMAP longas. A regra operacional é simples: se a migração começa bem e depois apresenta falhas intermitentes, reduza o ritmo antes de concluir que a senha está errada.

Aqui também fica clara a diferença entre o método antigo e o novo.

Método antigo: criar scripts para cada caixa, ajustar limites por tentativa e erro e acompanhar falhas às 2 da manhã.

Método novo: usar a importação no servidor integrada aos planos pagos da TrekMail para o recebimento, padronizar o destino e evitar cobrança por usuário. Agências com muitos domínios normalmente valorizam mais não passar três dias analisando novas tentativas do que terminar uma caixa dez minutos antes. Se esse for o seu caso, leia este guia de hospedagem para vários domínios.

Parâmetros de autenticação para 2025-2026: senhas falham, OAuth prevalece

No Google Workspace e no Microsoft 365, não é mais seguro presumir que usuário e senha simples funcionarão no IMAP. O Google informa que, a partir de May 1, 2025, contas Workspace deixaram de aceitar “aplicativos menos seguros” que entram apenas com usuário e senha. A orientação do Exchange Online também direciona clientes IMAP para OAuth.

Isso muda o uso do imapsync. Se a origem aceita XOAUTH2, use um token de acesso no lugar da senha comum do usuário.

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

No Google Workspace, senhas de app ainda podem servir para migrações pontuais quando a 2-Step Verification está ativa. No Microsoft 365, use o fluxo OAuth documentado para protocolos antigos. Se seu script ainda pressupõe que “senha correta significa autenticação correta”, ele não acompanha a realidade atual.

Fontes oficiais: orientação do Google Workspace sobre aplicativos menos seguros e instruções da Microsoft sobre OAuth para IMAP.

Parâmetros de integridade que evitam que o imapsync pule mensagens ruins

Algumas mensagens estão danificadas. Isso é normal em servidores antigos. Cabeçalhos Message-ID ausentes, MIME malformado, anexos enormes e conteúdos de zero bytes aparecem em migrações reais. O imapsync pode contornar parte disso, mas precisa receber instruções.

O primeiro parâmetro útil é --addheader. A documentação oficial diz que ele adiciona um cabeçalho Message-Id gerado quando a mensagem não possui um. Isso importa porque a identidade da mensagem ajuda o imapsync a decidir o que já existe.

O segundo é --maxsize. Se a caixa ou a política de destino rejeita mensagens enormes, não permita que uma delas pare toda a tarefa.

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

Não se trata de fingir que mensagens grandes não existem. Trata-se de mover primeiro os 99% e depois tratar as exceções manualmente com uma lista controlada.

Se você prepara muitas caixas em paralelo, associe isso a um processo organizado de provisionamento. Vale ler o guia da TrekMail para criar contas em massa, pois os problemas aumentam quando criação, entrega de senhas e DNS são gerenciados em planilhas separadas.

O parâmetro do imapsync que causa as piores perdas: --delete2

`--delete2` manda o imapsync remover do destino mensagens que não existem na origem. Isso parece útil para espelhamento exato. Também é uma maneira fácil de apagar mensagens novas e válidas após a virada do MX se for usado na hora errada.

Esta é a sequência da falha:

1. Você prepara no destino as mensagens antigas da origem.
2. Altera o MX para o novo provedor.
3. Mensagens novas começam a chegar ao destino.
4. Executa novamente o imapsync com --delete2.
5. O imapsync encontra mensagens exclusivas do destino e as apaga porque nunca existiram na origem.

Isso não é um defeito. É exatamente a instrução fornecida.

Use `--delete2` apenas num espelhamento controlado antes da virada, quando ambos os lados ainda estão vinculados à antiga fonte de verdade. Depois da mudança do MX, retire-o do comando. Se o destino já recebe mensagens, trate-o como autoridade para mensagens novas.

Quando os UIDs enganam, use correspondência por cabeçalho

UIDs IMAP só são confiáveis dentro do estado do servidor ao qual pertencem. A RFC 3501 define UIDVALIDITY justamente porque as suposições sobre UID podem falhar quando a caixa muda. Se uma pasta for reconstruída ou reindexada, o imapsync pode interpretar todas as mensagens como novas e duplicá-las numa passagem posterior.

Nesse caso, a correspondência por cabeçalho ajuda:

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'

É mais lento que confiar nos UIDs do servidor, mas é mais seguro quando a origem está instável, foi reconstruída ou mostra inconsistências. A documentação oficial observa que problemas de duplicação muitas vezes são resolvidos com --useheader "Message-Id".

Para a verificação final, prefiro uma passagem simulada com correspondência conservadora antes da mudança de DNS e uma passagem incremental curta depois que os usuários param de alterar o sistema antigo.

Um modelo seguro de comando imapsync

Uma execução segura explicita conexão, mapeamento, exclusões e modo de teste. Comece com simulação, confirme o comportamento das pastas e só então faça a passagem real. Não teste o primeiro rascunho do comando em mensagens de produção.

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

Três observações práticas:

1. Use --dry primeiro. Sempre.
2. Exclua na primeira passagem grandes pastas de arquivo desnecessárias.
3. Guarde o log e versione as linhas de comando de cada lote.

Quando a caixa chegar à TrekMail, os usuários podem usar IMAP padrão em imap.trekmail.net na porta 993. A TrekMail usa IMAP, não POP3, uma escolha adequada para manter o estado sincronizado entre dispositivos.

Conclusão: o imapsync funciona quando é operado como ferramenta de migração

O imapsync continua sendo apropriado para muitas mudanças de e-mail, desde que seja tratado como software com estado, não como simples comando de cópia. Defina tempos limite. Use keepalives. Mapeie pastas deliberadamente. Diminua o ritmo quando o provedor limitar. Use autenticação moderna. Mantenha `--delete2` longe das mensagens posteriores à virada. Quando o estado de UID estiver duvidoso, force a correspondência por cabeçalho.

Para facilitar o gerenciamento do destino, a TrekMail oferece vários domínios, preços fixos, armazenamento compartilhado, importação integrada no servidor em planos pagos e sem tarifa adicional a cada nova caixa. Como referência operacional após a mudança, leia em seguida este artigo sobre e-mail empresarial.