README.md

Mailbox Zero - Email Cleanup Helper

A Go-based web application that helps you clean up your email inbox by finding and archiving similar emails. Supports JMAP (Fastmail) and IMAP (Gmail, Outlook, etc.) protocols.

Features

• Multiple Protocols: JMAP (Fastmail) ✅ and IMAP (Gmail, Outlook, etc.) ✅
• Safe Operations: Built-in dry run mode prevents accidental changes
• Dual-pane Interface: View inbox on left, grouped similar emails on right
• Smart Similarity Matching: Fuzzy matching based on subject, sender, and email content
• Adjustable Similarity Threshold: Fine-tune matching with a percentage slider
• Selective Archiving: Choose which emails to archive with confirmation dialog
• Individual Email Selection: Select specific emails to find similar matches
• Mock Mode: Test without any email account credentials

Safety Features

• DRY RUN MODE: All write operations are disabled by default
• Archive Only: The only write operation is moving emails to archive (never deletes)
• Confirmation Dialog: Requires confirmation before archiving
• Visual Warnings: Clear indication when in dry run mode

Setup

Prerequisites

• Go 1.21 or later
• Email account with one of:
  • JMAP: Fastmail account with API token ✅
  • IMAP: Gmail, Outlook, or any IMAP provider ✅
• Or use Mock Mode for testing (no account required)

Installation

1. Clone/download the project

2. Install dependencies:

   go mod download

3. Create your configuration file:

   cp config.yaml.example config.yaml

4. Edit config.yaml with your email provider credentials:

   For JMAP (Fastmail):

   protocol: "jmap"
   jmap:
     endpoint: "https://api.fastmail.com/jmap/session"
     api_token: "your-api-token-here"
   dry_run: true

   For IMAP (Gmail, Outlook, etc.):

   protocol: "imap"
   imap:
     host: "imap.gmail.com"
     port: 993
     username: "your-email@gmail.com"
     password: "your-app-password"
     use_tls: true
     archive_folder: "[Gmail]/All Mail"
   dry_run: true

   For Mock Mode (no credentials needed):

   # JMAP Mock Mode
   protocol: "jmap"
   mock_mode: true
   dry_run: true

   Or for IMAP mock mode:

   # IMAP Mock Mode
   protocol: "imap"
   mock_mode: true
   dry_run: true

Getting Fastmail API Token

1. Log into your Fastmail account
2. Go to Settings → Privacy & Security → Integrations
3. Click "New API Token"
4. Set the scope to "Mail" access
5. Generate the token and copy it to your config file

Running the Application

1. Start the server:

   go run main.go

2. Open your browser to: http://localhost:8080

3. The application will display a warning banner when in dry run mode

Usage

Basic Workflow

1. Load Inbox: The left pane shows your current inbox emails
2. Find Similar Emails:
   • Click "Find Similar Emails" to find all similar email groups
   • Or select a specific email and click "Find Similar Emails" to find matches for that email
3. Adjust Similarity: Use the percentage slider to fine-tune matching sensitivity
4. Review Matches: Similar emails appear in the right pane with checkboxes
5. Select for Archiving: Choose which emails to archive (all selected by default)
6. Archive: Click "Archive Selected" and confirm to move emails to archive folder

Key Features

• Similarity Slider: Adjust from 0-100% to control how strict the matching should be
• Select All/None: Quickly select or deselect all found similar emails
• Individual Selection: Click on specific emails to select/deselect them
• Clear Results: Remove all results from the right pane to start fresh

Enabling Real Changes

⚠️ WARNING: Only disable dry run mode when you're confident the application works correctly with your mailbox.

1. Edit config.yaml:

   dry_run: false

2. Restart the application

3. The warning banner will disappear

4. Archive operations will now actually move emails

Configuration Options

server:
  port: 8080              # Web server port
  host: "localhost"       # Web server host

jmap:
  endpoint: "https://api.fastmail.com/jmap/session"
  api_token: ""           # Your Fastmail API token

dry_run: true             # Safety feature - set to false to enable changes
default_similarity: 75    # Default similarity percentage (0-100)

How Similarity Matching Works

The application uses fuzzy matching with weighted scoring:

• Subject Similarity (40%): Compares email subjects using Levenshtein distance
• Sender Similarity (40%): Compares sender email addresses
• Content Similarity (20%): Compares email preview/body content

Additional boosters:

• Common words in subjects increase similarity
• Normalized text (lowercase, punctuation removed) for better matching

Security Considerations

• API Tokens: Use Fastmail API tokens for secure authentication
• Local Only: All processing happens locally - no data sent to external servers
• Read-Heavy: Only reads email data, minimal write operations
• Archive Only: Never deletes emails, only moves them to archive

Troubleshooting

Authentication Errors

• Verify your Fastmail API token is correct
• Ensure JMAP is enabled in your Fastmail account
• Check network connectivity

No Emails Found

• Verify you have emails in your inbox
• Check if your account has the expected mailbox structure

Similarity Issues

• Try adjusting the similarity threshold
• Some emails may have very little content to compare
• Ensure emails have sufficient text in subject/preview

Development

The project structure:

mailboxzero/
├── main.go                 # Application entry point
├── config.yaml            # Configuration file
├── internal/
│   ├── config/            # Configuration handling
│   ├── protocol/          # Generic protocol abstraction layer
│   ├── providers/         # Email protocol implementations
│   │   ├── jmap/          # JMAP client (Fastmail)
│   │   └── imap/          # IMAP client (Gmail, Outlook, etc.)
│   ├── server/            # Web server and API handlers
│   └── similarity/        # Email similarity algorithms
└── web/
    ├── templates/         # HTML templates
    └── static/           # CSS and JavaScript files

Running Tests

The project includes comprehensive unit tests for all packages:

# Run all tests
go test ./...

# Run tests with verbose output
go test ./... -v

# Run tests with coverage
go test ./... -cover

# Generate coverage report
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out

License

This project is licensed under the MIT License - see the LICENSE file for details.