# Research: Ferramentas de Migração de E-mail (013)

**Data:** 2026-06-10  
**Autor:** Cursor Agent (para Roger)  
**Objetivo:** Seleccionar stack open-source com precisão, suporte a múltiplos formatos e operação **antes** do cutover DNS.

---

## Critérios de avaliação

| Critério | Peso | Descrição |
|----------|------|-----------|
| **Integridade** | P0 | Sem perda de mensagens; sem duplicatas; preservar pastas |
| **Retomável** | P0 | Sync incremental; reinício após falha |
| **Formatos** | P0 | IMAP, PST, mbox, EML, TGZ (Zimbra/Carbonio) |
| **Verificação** | P0 | Contagens, logs, comparadores |
| **Produção** | P1 | Usado em migrações reais; manutenção activa |
| **OAuth/M365** | P1 | Office 365 / Google modernos |
| **Licença** | P1 | Open source ou uso comercial permitido |

---

## Matriz de ferramentas (decisão)

### 1. IMAP → IMAP (servidor a servidor) — **PRIMÁRIO**

| Ferramenta | Repo / URL | Stars | Veredito |
|------------|------------|-------|----------|
| **imapsync** | https://github.com/imapsync/imapsync | ~4k | ✅ **Escolhido — motor principal** |
| doveadm backup/sync | https://doc.dovecot.org/latest/core/admin/migration.html | — | ✅ Secundário se origem/destino Dovecot |
| offlineimap / mbsync | vários | — | ❌ Menos adequado a migração one-way em massa |

**Porquê imapsync:**
- Padrão de facto para migração IMAP entre fornecedores (cPanel, Zimbra, O365, Gmail → Carbonio).
- Sync **incremental e recursivo** — pode correr dias antes do DNS.
- Evita duplicatas; retomável.
- Suporte OAuth2 via `oauth2_imap` (site oficial imapsync.lamiral.info).
- Documentação extensa (FAQ, casos Exchange/Gmail).

**Quando doveadm:**
- Ambos os lados Dovecot/Carbonio com acesso admin.
- Verificação UIDL mais rigorosa (documentação Dovecot recomenda `diff` manual).

---

### 2. PST / OST (Microsoft Outlook) — **PIPELINE OFICIAL**

| Etapa | Ferramenta | Repo / pacote | Veredito |
|-------|------------|---------------|----------|
| PST → mbox | **readpst** (libpst) | `pst-utils` / https://www.five-ten-sg.com/libpst/ | ✅ Extracção battle-tested |
| mbox → IMAP | **imap-upload** | https://github.com/rgladwell/imap-upload (~148⭐) | ✅ Upload para Carbonio via IMAP |
| Wrapper moderno | **pst2mbox** | https://github.com/beaufour/pst2mbox | ✅ Progress bar, resumível, arquitectura modular |

**Pipeline Ligbox (PST):**
```
.pst → readpst -o mbox -r arquivo.pst
     → imap-upload.py --ssl --host mail.destino --user conta@dominio ...
     → validação contagem + amostra
```

**Riscos PST (mitigação na spec):**
- PST corrompido → `readpst` com log; quarentena em `ERR_MBOX` (flag `--error` do imap-upload).
- RTF vs HTML → não usar `-b` em PST antigos (pré-2010).
- Pastas Outlook → mapear estrutura `readpst` para IMAP com prefixo `INBOX.`.
- **Não** depender só de drag-and-drop Outlook (manual, não auditável).

**pst2mbox** recomendado como wrapper futuro (Fase B) — encapsula readpst + upload com progresso.

---

### 3. Zimbra / Carbonio (mesma família) — **NATIVO**

| Método | Comando | Veredito |
|--------|---------|----------|
| Export TGZ | `zmmailbox -z -m user getRestURL '/?fmt=tgz'` | ✅ Bulk, preserva metadados |
| Import TGZ | `zmmailbox -z -m user postRestURL "/?fmt=tgz&resolve=skip" ficheiro.tgz` | ✅ Destino Carbonio |
| IMAP fallback | imapsync | ✅ Zimbra antigo → Carbonio novo |

**Ordem Zextras Community (referência):**
1. Criar contas no destino  
2. **Migrar dados (TGZ ou imapsync)**  
3. **Só depois** alterar MX/DNS  
4. Sync final pós-DNS  

Fonte: [Zimbra → Carbonio CE migration](https://community.zextras.com/how-to-use-script-to-migrate-zimbra-to-carbonio-carbonio-ce/)

---

### 4. mbox / EML avulso

| Ferramenta | Uso |
|------------|-----|
| imap-upload | mbox → IMAP Carbonio |
| `zmmailbox addMessage` | EML individual no Carbonio (admin) |
| ImportExportTools NG (Thunderbird) | Fallback manual auditado |

---

### 5. Office 365 / Gmail

| Ferramenta | Notas |
|------------|-------|
| imapsync + oauth2_imap | O365 exige OAuth; não usar password básica |
| imap-upload `--office365` / `--gmail` | Upload mbox para destinos cloud |

---

### 6. Ferramentas comerciais (referência — **fora do MVP**)

| Ferramenta | Motivo exclusão MVP |
|------------|---------------------|
| BitRecover / Advik / TrustVare | Fechadas; sem API; sem integração Desk |
| MailStore | Trial; possível Fase C para auditoria legal |

---

## Stack aprovada para Spec 013

```
┌─────────────────────────────────────────────────────────────────┐
│                  Ligbox Ops — Migration Orchestrator            │
│                     (VM122 API + Worker)                        │
└────────────────────────────┬────────────────────────────────────┘
                             │
     ┌───────────────────────┼───────────────────────┐
     │                       │                       │
     ▼                       ▼                       ▼
┌─────────┐          ┌─────────────┐         ┌──────────────┐
│ imapsync│          │ readpst     │         │ zmmailbox    │
│ (IMAP)  │          │ + imap-upload│        │ tgz export/  │
│         │          │ (PST/mbox)  │         │ import       │
└────┬────┘          └──────┬──────┘         └──────┬───────┘
     │                      │                       │
     └──────────────────────┼───────────────────────┘
                            ▼
                   ┌─────────────────┐
                   │ Carbonio VM112  │
                   │ (destino IMAP)  │
                   └─────────────────┘
                            │
                   ┌────────▼────────┐
                   │  GATE: DNS OK   │  ← só após migration_gate=ready
                   └─────────────────┘
```

---

## Verificação de integridade (obrigatória)

| Check | Ferramenta / método |
|-------|---------------------|
| Contagem mensagens por pasta | imapsync log + IMAP `STATUS` / `SEARCH ALL` |
| Contagem global | Script Python `migration_verify.py` (a criar) |
| Amostra corpo/anexos | 5 msgs aleatórias por pasta crítica |
| UIDL (Dovecot) | `doveadm fetch -u user uidl` + diff |
| PST | `readpst -S` stats vs destino |
| Falhas upload | `ERR_MBOX` do imap-upload preservado |

**Regra:** `migration_gate` **bloqueia** cutover DNS se `messages_dest < messages_source * 0.99` ou checks críticos falharem.

---

## Dependências de sistema (worker VM122 ou jump host)

```bash
# Debian/Ubuntu
apt-get install -y imapsync pst-utils python3 python3-pip
pip3 install pst2mbox  # Fase B opcional

# imap-upload
git clone https://github.com/rgladwell/imap-upload.git /opt/migration-tools/imap-upload
```

**Carbonio (VM112):** `zmmailbox`, `zmprov` — já presentes.

---

## Referências

- imapsync: https://github.com/imapsync/imapsync · https://imapsync.lamiral.info/
- Dovecot migration: https://doc.dovecot.org/latest/core/admin/migration.html
- imap-upload: https://github.com/rgladwell/imap-upload
- pst2mbox: https://github.com/beaufour/pst2mbox
- libpst/readpst: https://www.five-ten-sg.com/libpst/
- Carbonio PST forum: https://community.zextras.com/forum/carbonio-general-thread/importing-outlook-pst-files-into-carbonio/
- Zimbra→Carbonio SOP: https://community.zextras.com/how-to-use-script-to-migrate-zimbra-to-carbonio-carbonio-ce/