coldmail 0.5.0
Encrypted, searchable, portable Gmail archive
Requires Python: >=3.8
Keywords: archive, backup, email, encryption, gmail, veracrypt

# 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

```bash
pip install coldmail
```

### 2. Install dependencies

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

### 3. Create your archive

```bash
coldmail init
```

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

### 4. Export your Gmail

Go to [Google Takeout](https://takeout.google.com):
- Select **Gmail only**
- Choose **MBOX format**
- Download when ready

### 5. Import and search

```bash
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`](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:

```bash
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](https://veracrypt.fr/)** - AES-256 encrypted volume (the `.vc` file)
- **[Bichon](https://github.com/rustmailer/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](docs/security-model.md) for details.

## Requirements

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

## License

MIT - See [LICENSE](LICENSE)

## Credits

Built on [Bichon](https://github.com/rustmailer/bichon) (AGPLv3) and [VeraCrypt](https://veracrypt.fr/).