coldmail 0.5.0

Encrypted, searchable, portable Gmail archive

Coldmail

Encrypted, searchable, portable Gmail archive.

Archive years of Gmail into a single encrypted file. Search it offline with a native-feeling web UI. Keep your email history safe from third-party AI tools, data breaches, and prying eyes.

Why Coldmail?

If you use agentic AI tools (OpenClaw, etc.) that access your email, your entire history is exposed. Coldmail lets you:

• Archive old emails (>1-2 years) out of Gmail
• Encrypt them in a single portable file (AES-256)
• Search them offline with a Gmail-like web interface
• Lock everything behind a password when not in use
• Backup safely to any cloud storage (it's just an opaque encrypted blob)

Quick Start

1. Install Coldmail

pip install coldmail

2. Install dependencies

coldmail setup
# Or manually:
# macOS:  brew install --cask docker macfuse veracrypt
# Linux:  sudo apt install docker.io veracrypt

3. Create your archive

coldmail init

You'll be asked for a volume size (default: 50GB) and a password.

4. Export your Gmail

Go to Google Takeout:

• Select Gmail only
• Choose MBOX format
• Download when ready

5. Import and search

coldmail start                           # Mount + start web UI
coldmail import ~/Downloads/Gmail.mbox   # Import your emails
# Open http://localhost:15630 and search!
coldmail stop                            # Lock everything

Usage via AI Agent

Coldmail is designed to be operated end-to-end by an AI agent (Claude, etc.) on your behalf. Every command supports non-interactive flags so no stdin prompts block automation.

Just tell your AI assistant:

"Archive my Gmail with this project: https://github.com/cedric-coroir/coldmail"

The agent reads AGENT.md for step-by-step operational instructions.

Commands

Command	Description
coldmail setup	Install deps, start Docker, pull Bichon image
coldmail init	Create a new encrypted archive
coldmail start	Mount archive and start web UI
coldmail stop	Stop web UI and lock archive
coldmail status	Show current status (--json for machine-readable)
coldmail doctor	Pre-flight check: deps, daemon, volume, image
coldmail accounts	List imported email accounts (--json)
coldmail clean	Scan Gmail to exclude newsletter senders
coldmail import <mbox>	Import a Google Takeout MBOX file
coldmail gmail-setup	Guide for connecting Gmail via IMAP
coldmail backup <path>	Backup archive to a location
coldmail destroy	Permanently delete archive

Newsletter Cleaner

Before importing, you can scan your Gmail to identify newsletter senders:

coldmail clean

This connects to Gmail (read-only), finds all senders with "unsubscribe" links, and lets you choose which to exclude. Only the emails you want are imported.

How It Works

                    coldmail start
                         |
Gmail ──Takeout──> MBOX ──import──> [VeraCrypt Volume]
                                         |
                                    [Bichon in Docker]
                                         |
                                    localhost:15630
                                    (search web UI)

                    coldmail stop
                         |
                    [Volume locked]
                    emails.vc = opaque encrypted file

Components:

• VeraCrypt - AES-256 encrypted volume (the .vc file)
• Bichon - Rust email archiver with React web UI and Tantivy full-text search
• Docker - Runs Bichon in an isolated container

Portability

To move your archive to another machine:

1. Copy emails.vc (your encrypted archive)
2. Install Docker + VeraCrypt + Coldmail
3. Run coldmail start

That's it. Everything is in the encrypted file.

Security Model

• All emails stored in AES-256 encrypted volume
• Password never stored anywhere
• When stopped: archive is an opaque encrypted file
• Bichon binds to 127.0.0.1 only (no network exposure)
• Gmail API token deleted after newsletter scan
• Safe to backup to any cloud storage

See Security Model for details.

Requirements

• Python 3.8+
• Docker
• VeraCrypt (+ macFUSE on macOS)
• 10GB+ free disk space

License

MIT - See LICENSE

Credits

Built on Bichon (AGPLv3) and VeraCrypt.