Getting Started with MailHelm

Quick Start Guide

Welcome to MailHelm! Follow these steps to get up and running in under 5 minutes.

1. Download & Install — Get the latest version for your platform.
2. Create Master Password — This encrypts all your data locally. Choose a strong password you can remember.
3. Add Email Account — Connect your first email account using IMAP credentials.
4. Start Managing — MailHelm will fetch and classify your emails using rules. Optionally add an AI provider for smart fallback classification.

Installation

Linux (AppImage)

# Download the AppImage
# Make it executable
chmod +x MailHelm-*.AppImage

# Run it
./MailHelm-*.AppImage

The AppImage is a self-contained package that works on most Linux distributions without installation. No root access required.

Master Password

Your master password is the key to all your encrypted data in MailHelm. It is used to derive an encryption key via PBKDF2 (100,000 iterations) which then encrypts your email credentials and other sensitive data using AES-256-GCM.

Important: Your master password is never stored anywhere. If you forget it, your encrypted data cannot be recovered. Please choose a strong, memorable password and store it safely.

Groq API Key (Recommended — Free)

Groq is the recommended AI provider — completely free with no region restrictions. Here's how to get your API key:

1. Go to Groq Console
2. Create an account (free)
3. Click "Create API Key"
4. Copy the key and paste it into MailHelm Settings > AI Configuration

Groq offers generous free usage limits and works worldwide without region restrictions.

Gemini API Key (Alternative)

Google Gemini is an alternative AI provider. Note: may have rate limits in some regions. Here's how to get your API key:

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the key and paste it into MailHelm Settings > AI Configuration

The free Gemini API has generous rate limits, though availability may vary by region.

Claude API Key

1. Visit Anthropic Console
2. Create an account and add billing
3. Generate an API key from the dashboard
4. Paste into MailHelm Settings > AI Configuration > Claude

OpenAI API Key

1. Visit OpenAI Platform
2. Create an account and add billing
3. Generate a new API key
4. Paste into MailHelm Settings > AI Configuration > OpenAI

Gmail Setup

Gmail requires an App Password for IMAP access. Follow these steps:

1. Enable 2-Step Verification in your Google Account security settings
2. Go to App Passwords
3. Select "Mail" and your device, then click "Generate"
4. Copy the 16-character password

IMAP Settings:

Hotmail / Outlook Setup

Yahoo Mail Setup

Yahoo also requires an App Password:

1. Go to Yahoo Account Security settings
2. Enable 2-Step Verification
3. Generate an App Password for "Other App"

Custom IMAP Server

MailHelm works with any standard IMAP server. You'll need:

• IMAP server hostname and port
• SMTP server hostname and port (for sending)
• Your username (usually email address) and password
• Security type (SSL/TLS or STARTTLS)

Telegram Bot Setup

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts to create a bot
3. Copy the Bot Token
4. Message your new bot to start a conversation
5. Get your Chat ID by messaging @userinfobot
6. Enter both the Bot Token and Chat ID in MailHelm Settings > Notifications > Telegram

WhatsApp Setup

WhatsApp notifications require the WhatsApp Business API. This is available on Pro and Business plans.

Configuration details will be available in the app settings once you activate a Pro or Business license.

Feishu / Lark Setup

Feishu (Lark) uses webhook URLs for notifications:

1. Open Feishu and go to the group where you want notifications
2. Click Settings > Bots > Add Bot > Custom Bot
3. Copy the Webhook URL
4. Paste into MailHelm Settings > Notifications > Feishu

Classification Rules

MailHelm uses a four-layer classification funnel per email account. This means your work email can have different rules than your personal email.

• Layer 1 — VIP Senders — Emails from VIP senders are always marked as urgent
• Layer 2 — Ignore Rules — Filter out newsletters, notifications, and noise
• Layer 3 — Custom Rules — Match by sender, subject, or content with trigger/action logic
• Layer 4 — AI Fallback — Unmatched emails go to AI for smart classification (optional)
• Folder Mappings — Map categories to specific IMAP folders, auto-created for new categories

Account Keep-Alive

The keep-alive engine uses Playwright to automate browser-based logins, preventing your accounts from being deactivated due to inactivity. Configure per account in Settings > Keep-Alive.

Note: Keep-alive is available for 5 accounts on Pro and unlimited on Business. The engine runs in the background with randomized timing to appear natural.

FAQ

Is my data safe?

Yes. All data is stored locally on your computer and encrypted with AES-256-GCM. Your master password derives the encryption key via PBKDF2. We have zero access to your data.

Does MailHelm read my emails?

MailHelm fetches email headers and content via IMAP for classification. The rules-based engine processes everything locally. If you enable AI classification, only sender and subject are sent to your chosen AI provider (Groq/Gemini/Claude/GPT). No email body content is sent to AI. No data is stored on our servers.

Can I use MailHelm offline?

MailHelm requires internet access to fetch emails (IMAP). Rules-based classification works without any external API. AI classification requires internet for API calls. Previously fetched and classified emails are always available offline from the local database.