Workflows

Workflows

Safe migration sequence

For an important account:

1. Count the source.
2. Make a local backup or perform a non-destructive migration.
3. Compare source and destination.
4. Investigate unexpected differences.
5. Only then consider source or destination deletion.

imap-count --target source
imap-migrate --no-src-delete --no-dest-delete
imap-compare

Count

imap-count --target source
imap-count --target destination
imap-count --target local

Backup and verify

imap-backup --dest-path ./mail-backup
imap-compare --dest-path ./mail-backup

Backups store messages as .eml files. Preserve flags and Gmail labels when required:

imap-backup --preserve-flags --preserve-labels

Migrate

Copy without deleting from either side:

imap-migrate --no-src-delete --no-dest-delete

Migrate one folder:

imap-migrate "Archive/2025"

Enable incremental migration caching:

imap-migrate --migrate-cache ./migration-cache

Use --full-migrate to ignore cached skip decisions while continuing to update an enabled cache.

Restore

imap-restore --src-path ./mail-backup

Apply a saved labels/flags manifest when restoring Gmail-oriented backups:

imap-restore --apply-labels --apply-flags

Destructive synchronization

--src-delete moves instead of copying after successful transfer. --dest-delete removes destination-only messages or files. Use these options only after comparing and validating the result.

See Configuration for precedence and Troubleshooting when results differ.