mail-migrator/README.md

Mail-Migrator

Email migration tools untuk memindahkan mailbox IMAP antar server dengan dukungan resume, batch processing, dan insecure mode.

Features

• ✅ Single & Batch Migration: Migrasi satu akun atau batch dari file CSV
• ✅ Resume Support: Lanjutkan migrasi yang terputus menggunakan BoltDB state tracking
• ✅ Insecure Mode: Terima self-signed certificates dengan flag --insecure
• ✅ Comprehensive Logging: Log ke console dan file dengan timestamp
• ✅ Mailbox Detection: Otomatis detect dan migrate semua mailbox/folder
• ✅ Batch Processing: Proses message dalam batch untuk efisiensi
• ✅ Error Handling: Robust error handling dengan retry logic

Installation

Build from Source

git clone <repository-url>
cd mail-migrator
go mod tidy
go build .

Download Binary

Download binary dari releases page atau build sendiri.

Usage

Single Account Migration

# Basic migration
./mail-migrator --src "user1:pass1@imap.old.com:993" \
                 --dst "user1:pass1@imap.new.com:993"

# With insecure mode (trust self-signed certs)
./mail-migrator --src "user1:pass1@imap.old.com:993" \
                 --dst "user1:pass1@imap.new.com:993" \
                 --insecure

# With resume support and logging
./mail-migrator --src "user1:pass1@imap.old.com:993" \
                 --dst "user1:pass1@imap.new.com:993" \
                 --insecure \
                 --resume \
                 --log migration.log

Batch Migration

Buat file CSV dengan format: source,destination

accounts.csv:

user1:pass1@old.com:993,user1:newpass1@new.com:993
user2:pass2@old.com:993,user2:newpass2@new.com:993
user3:pass3@old.com:993,user3:newpass3@new.com:993

# Batch migration
./mail-migrator --batch accounts.csv --insecure --resume --log batch.log

Command Line Options

Flag	Description	Default
--src	Source IMAP URL (user:pass@host:port)	-
--dst	Destination IMAP URL (user:pass@host:port)	-
--batch	CSV file with src,dst entries for batch migration	-
--insecure	Allow insecure TLS (trust self-signed certs)	false
--resume	Resume incomplete migrations	false
--state	Path to state DB (Bolt)	state.db
--log	Path to log file (optional)	-

URL Format

IMAP URL format: username:password@hostname:port

Examples:

• john:secret123@mail.example.com:993 (IMAPS)
• jane:mypass@imap.gmail.com:993 (Gmail)
• user@domain.com:password@mail.server.com:143 (IMAP plain)

Port defaults:

• Port 993: IMAPS (TLS/SSL)
• Port 143: IMAP (plain/STARTTLS)

Resume Functionality

Aplikasi menggunakan BoltDB untuk menyimpan state migrasi:

• State Key: source|destination|mailbox
• Tracking: Last migrated UID per mailbox
• Resume: Otomatis lanjut dari UID terakhir yang sukses
• File: Default state.db (bisa diubah dengan --state)

Logging

• Console: Selalu aktif dengan timestamp
• File: Optional dengan flag --log filename.log
• Format: [timestamp] [level] message
• Levels: INFO, WARN, ERROR, DEBUG

Error Handling

• Connection errors: Retry dengan backoff
• Authentication: Clear error message
• Mailbox errors: Skip dan lanjut ke mailbox berikutnya
• Message errors: Skip message yang corrupt, lanjut ke berikutnya
• Batch errors: Error di satu akun tidak stop seluruh batch

Performance

• Batch size: 50 messages per batch (configurable dalam code)
• Memory: Efficient streaming untuk message besar
• Concurrent: Single-threaded untuk stability
• Resume: Minimal overhead dengan UID tracking

Troubleshooting

Common Issues

1. Certificate Errors

x509: certificate signed by unknown authority

Solution: Gunakan flag --insecure

2. Authentication Failed

login failed: Invalid credentials

Solution:

• Cek username/password
• Untuk Gmail: gunakan App Password, bukan password biasa
• Cek apakah IMAP enabled di server

3. Connection Timeout

dial failed: i/o timeout

Solution:

• Cek hostname dan port
• Cek firewall/network connectivity
• Cek apakah server support IMAP

4. Mailbox Not Found

select source INBOX: Mailbox doesn't exist

Solution:

• Cek apakah mailbox ada di source
• Beberapa server case-sensitive untuk nama mailbox

Debug Mode

Untuk debug lebih detail, edit code dan set:

logrus.SetLevel(logrus.DebugLevel)

Examples

Gmail to Gmail

./mail-migrator --src "olduser@gmail.com:apppass1@imap.gmail.com:993" \
                 --dst "newuser@gmail.com:apppass2@imap.gmail.com:993" \
                 --insecure --resume --log gmail-migration.log

Office365 Migration

./mail-migrator --src "user@old.com:password@outlook.office365.com:993" \
                 --dst "user@new.com:password@outlook.office365.com:993" \
                 --resume --log o365-migration.log

Self-hosted with Self-signed Cert

./mail-migrator --src "user:pass@mail.old.local:993" \
                 --dst "user:pass@mail.new.local:993" \
                 --insecure --resume

Development

Project Structure

├── main.go          # CLI interface dan orchestration
├── imap.go          # IMAP connection dan message copying
├── state.go         # BoltDB state persistence
├── go.mod           # Go module dependencies
└── README.md        # Documentation

Dependencies

• github.com/emersion/go-imap - IMAP client library
• github.com/urfave/cli/v2 - CLI framework
• go.etcd.io/bbolt - Embedded key-value database
• github.com/sirupsen/logrus - Structured logging

Building

# Development build
go run . --help

# Production build
go build -ldflags="-s -w" .

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build .

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Add tests if applicable
5. Submit pull request

Support

For issues and questions:

1. Check troubleshooting section
2. Search existing issues
3. Create new issue with:
   • Command used
   • Full error message
   • Log output (with sensitive info removed)