Mailcow Alias Manager

Chrome and Firefox extension to manage aliases for a self-hosted Mailcow instance directly from the browser.

No local server required. The extension directly contacts your Mailcow API.

Features

• List, create, delete and toggle aliases
• Direct connection to your Mailcow instance (no proxy/backend)
• Secure API key storage via chrome.storage.sync
• HTTPS enforced (localhost exception for development)
• 13 languages supported
• Manifest V3 compatible (Chrome & Firefox)

Architecture

Extension (popup / options)
  ↓ fetch() with X-API-Key header
  ↓ host_permissions: https://*/* (Manifest V3)
Self-hosted Mailcow API (https://your-domain.com/api/v1/)

Installation

Chrome

1. Open chrome://extensions/
2. Enable "Developer mode"
3. Click "Load unpacked" → select the extension/ folder

Firefox

1. Open about:debugging
2. "This Firefox" → "Load Temporary Add-on"
3. Select extension/manifest.json

Configuration

1. Click on the extension icon → "Configure now" (or open the Options page)
2. Enter:
   • Mailcow URL: https://mail.your-domain.com
   • API Key: generated in Mailcow → Configuration → Access → API
3. "Test connection" → "Save"

Project Structure

.
├── extension/
│   ├── manifest.json           # Manifest V3 (host_permissions)
│   ├── js/
│   │   ├── mailcow-api.js     # ES Module — Mailcow API client
│   │   └── i18n.js            # Internationalization helper
│   ├── popup/                  # Main interface (alias list + CRUD)
│   ├── options/                # Configuration page (URL + API key)
│   ├── background/             # Service worker (badge + first-install)
│   └── _locales/               # 13 languages (en, fr, de, es, it, ja, ko, nl, pl, pt_BR, ru, tr, zh_CN)
├── package.sh                  # Build script for Chrome/Firefox distribution
└── .github/                    # Copilot instructions, agents and skills

Security

• API key stored in chrome.storage.sync (natively encrypted by browser/OS)
• Never sent to a third-party server — only to your Mailcow instance
• HTTPS enforced for all non-localhost connections
• User input validation (email format)
• AbortController timeout (10s) on each request
• Connection tested before saving credentials

Packaging

To generate .zip files ready for store publication:

chmod +x package.sh
./package.sh
# → dist/mailcow-alias-v0.1.0-chrome.zip
# → dist/mailcow-alias-v0.1.0-firefox.zip

Version is read automatically from extension/manifest.json.

Chrome Web Store

1. Go to the Chrome Web Store Developer Dashboard
2. Create a new item and upload dist/mailcow-alias-vX.Y.Z-chrome.zip

Firefox Add-ons (AMO)

1. Go to the Add-on Developer Hub
2. "Submit a New Add-on" and upload dist/mailcow-alias-vX.Y.Z-firefox.zip

License

MIT