Gmail Alias Toolkit

About

# 📧 Gmail Alias Toolkit

A powerful browser extension for generating and managing Gmail aliases using plus addressing (+tag). Streamline your email workflow with random generators, custom presets, favorites, and comprehensive statistics.

## ✨ Features

### 🎯 Core Features
- Random Alias Generator: Generate secure random aliases with multiple format options
  - Private Mail format (e.g., `private-mail-q2ga`)
  - Alphanumeric (e.g., `abc123xy`)
  - Random Words (e.g., `happy-fox-42`)
  - Timestamp-based (e.g., `lk9x2m3n`)
- Custom Tags: Create aliases with your own custom tags
- Gmail Tricks: Quick access to Gmail filtering and management tricks
- Built-in Presets: Shopping, Work, Test, Social, Finance, Travel
- Custom Presets: Create and manage unlimited preset tags with context menu integration
- Favorites System: Star frequently used aliases for instant access
- Recent Aliases: View, search, filter, and manage alias history with pagination
- Multi-Account Support: Switch between multiple Gmail accounts seamlessly
- Statistics Dashboard: Track usage with detailed analytics and insights
- Badge Counter: Display alias count on extension icon (Total, Today, Week, or All-Time)

### 🎨 UI/UX Features
- Modern Design: Clean, gradient-based interface with card layouts
- Tabbed Interface: Organized main view with Random, Custom, and Gmail Tricks tabs
- Pagination: Navigate through large alias histories (5-50 items per page)
- Search & Filter: Real-time search and tag-based filtering
- View Modes: Switch between Recent and Favorites views
- Responsive: Optimized for 360px extension popup
- Context Menu: Right-click integration for quick alias generation on any editable field

### ⚙️ Settings & Customization

#### General Settings
- Badge Counter: Choose what to display on extension icon
  - None (Hidden)
  - Total in History
  - Total Generated (All Time)
  - Created Today
  - This Week
- Random Format: Select default format for random alias generation
- Auto-save Limit: Set history size (20-500 aliases)
- Theme: Light mode (Dark mode coming in next update)
- Show Notifications: Toggle copy confirmation messages

#### Account Management
- Multi-Account: Add, edit, delete, and switch between Gmail accounts
- Account Labels: Organize accounts with custom labels (Work, Personal, etc.)
- Data Isolation: Each account has separate history, stats, and favorites
- Quick Add: Add accounts directly from Settings with auto-complete
- Email Migration: Change account email while preserving all data

#### Custom Presets
- Add unlimited custom preset tags
- Synced with context menu automatically
- Dynamic creation and deletion
- Display with colored badges

#### Data Management
- Export Settings: Download all settings as JSON backup
- Import Settings: Restore settings from backup file
- Clear History: Remove all recent aliases for active account
- Reset Settings: Restore all defaults with confirmation

## 🛠 Tech Stack

- WXT: Modern web extension framework
- React 18: UI library
- TypeScript: Type safety
- Tailwind CSS: Styling (CSP-safe, no CDN)
- Manifest V3: Latest Chrome extension standard

## 📦 Installation

### Development
```bash
# Install dependencies
pnpm install
# or
yarn install

# Start development server
pnpm dev
# or
yarn dev
```

### Build for Production
```bash
# Build extension
pnpm build
# or
yarn build

# Create distributable zip
pnpm zip
# or
yarn zip
```

### Load in Chrome
1. Run `pnpm dev` or `yarn dev`
2. Open Chrome and go to `chrome://extensions/`
3. Enable "Developer mode"
4. Click "Load unpacked"
5. Select the `.output/chrome-mv3` folder

## 📖 How to Use

### Generate an Alias

1. Set Your Base Email
   - Enter your Gmail address (e.g., `[email protected]`)
   - The extension validates it's a Gmail address

2. Use Quick Presets
   - Click any preset button (Shopping, Work, etc.)
   - Alias is automatically generated and copied

3. Create Custom Alias
   - Type a custom tag in the input field
   - Click "Generate" or press Enter
   - Alias is copied to clipboard

### Manage Custom Presets

1. Click the ⚙️ Settings icon
2. Go to "Presets" tab
3. Enter preset label and tag
4. Click "Add Preset"
5. Your preset appears in the main view (purple style)

### Add to Favorites

1. In the Favorites section, click "+ Add"
2. Enter a label (e.g., "Amazon")
3. Enter the tag (e.g., "amazon")
4. Click "Add"
5. Access with one click anytime

### View Statistics

1. Click "View Statistics" in the main popup
2. See:
   - Total aliases generated
   - Daily and weekly counts
   - Most used tag
3. Click the X to collapse

### Export/Import Settings

#### Export
1. Open Settings → Advanced tab
2. Click "Export Settings"
3. JSON file downloads automatically
4. Save for backup

#### Import
1. Open Settings → Advanced tab
2. Click "Import Settings"
3. Select your JSON backup file
4. All settings restore instantly

### Search Recent Aliases

1. When you have 4+ recent aliases
2. Search box appears automatically
3. Type to filter aliases in real-time
4. Click any alias to copy

## 🎨 UI/UX Design

- Clean & Modern: Professional SaaS-style design
- Card-Based Layout: Organized information hierarchy
- Responsive: Works perfectly at 360px max width
- Intuitive Icons: Clear visual indicators
- Color-Coded: Different colors for different sections
  - Blue: Primary actions and default presets
  - Purple: Custom presets
  - Yellow: Favorites
  - Green: Success states
  - Red: Danger zone actions

## 🔐 Privacy & Security

- Local Storage Only: All data stored locally in your browser
- No Analytics: No tracking or data collection
- No External Calls: Works completely offline
- No Permissions Abuse: Only requests necessary permissions:
  - `storage`: Save settings and history
  - `clipboardWrite`: Copy aliases to clipboard