gerald

Gerald is a Gmail backup tool that downloads all messages from a Gmail account to a local mbox file. It supports incremental backups by date range, dry-run mode, checkpoint/resume for interrupted downloads, and optional server-side deletion.

Setup

1. Google Cloud Project & OAuth Consent

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Navigate to APIs & Services > Library and enable the Gmail API.
4. Go to APIs & Services > Credentials and click Create Credentials > OAuth client ID.
5. Set the application type to Desktop app and give it a name.
6. Download the JSON credentials file.

2. Configure Credentials

Set the following environment variables:

export GOOGLE_CLIENT_ID="<your-client-id>"
export GOOGLE_CLIENT_SECRET="<your-client-secret>"

Alternatively, create a YAML config file:

client_id: "<your-client-id>"
client_secret: "<your-client-secret>"

3. First Run

On first run, Gerald will display an authorization URL. Open it in your browser, grant access, and paste the verification code back into the terminal. The OAuth token is cached locally for subsequent runs.

Usage

# Download all messages
gerald

# Download messages from a specific date
gerald --date 2024-01-01

# Download messages since a specific date (RFC3339)
gerald --date 2024-01-01T00:00:00Z

# Specify output file
gerald --output backup.mbox
gerald -o backup.mbox

# Download and trash messages after successful backup
gerald --delete

# Permanently delete instead of trashing
gerald --delete --permanent

# Dry-run: download and write mbox but skip deletion
gerald --delete --dry-run

# Interactive confirmation before deletion
gerald --delete --confirm

# Verbose logging
gerald --verbose
gerald -v

# Use a config file
gerald --config config.yaml

# Combination: backup since a date, trash with confirmation
gerald --date 2023/06/01 --delete --confirm -o june2023.mbox

Crash Recovery

If Gerald is interrupted during a download (Ctrl+C, network failure, etc.), it resumes automatically on the next run. A checkpoint file (.ckpt) tracks how many messages were written to the temp file (.tmp). On restart, Gerald detects both files and appends remaining messages where it left off. The checkpoint is removed on successful completion.

# If interrupted, just run the same command again — it resumes
gerald --date 2024-01-01 --delete

Output Format

Gerald produces files in mboxrd format (RFC 4155), the most widely compatible mbox variant.

Compatibility

Application	Status
Mozilla Thunderbird	Full support. Import via Tools > Import > Mail > mbox.
Apple Mail	Full support. Rename to .mbox and double-click to import.
mutt	Full support. Set folder to the mbox file path.
Pine / Alpine	Full support.
Procmail	Full support.
mailx / Heirloom mailx	Full support.

The mboxrd format stores messages sequentially, each preceded by a From envelope line. Lines in message bodies that start with From are prefixed with > to distinguish them from envelope delimiters. Gerald preserves the full raw email content including all headers, MIME structure, and attachments without modification.

Build

go build -o gerald ./cmd/gerald

License

MIT