KISS Mail

A dead-simple email server. SMTP, IMAP, and POP3 in one container.

Quick Start (Docker)

# Run with Docker (recommended)
docker run -d \
  --name kiss-mail \
  -p 25:2525 -p 587:2525 \
  -p 143:1143 -p 110:1100 \
  -p 8080:8080 \
  -v kiss-mail-data:/data \
  -e KISS_MAIL_DOMAIN=mail.example.com \
  ghcr.io/pegasusheavy/kiss-mail:latest

# Access web admin
open http://localhost:8080/admin

That's it. The server starts and creates an admin account automatically.

One-Line Deploy (Any VPS)

curl -fsSL https://raw.githubusercontent.com/pegasusheavy/kiss-mail/main/deploy/scripts/install.sh | sudo bash

Build from Source (Optional)

cargo build --release
./target/release/kiss-mail

Usage

# Start the server
kiss-mail

# Create a user
kiss-mail add alice mysecretpassword

# List users
kiss-mail list

# Change a password
kiss-mail passwd alice newpassword

# Delete a user
kiss-mail del alice

# Show stats
kiss-mail stats

Connect Your Email Client

Environment Variables

Docker (Recommended)

Docker is the preferred deployment method for KISS Mail.

Security

Our containers are built on Docker Hardened Images (Alpine-based):

• Zero known CVEs - Continuously scanned and patched
• Minimal attack surface - Alpine Linux base (~5MB)
• SBOM included - Full software bill of materials
• Non-root user - Runs as unprivileged user
• Cryptographically signed - Verifiable authenticity

Pull from Registry

# Pull the official hardened image
docker pull ghcr.io/pegasusheavy/kiss-mail:latest

# Run container
docker run -d \
  --name kiss-mail \
  --restart unless-stopped \
  -p 25:2525 -p 587:2525 \
  -p 143:1143 -p 110:1100 \
  -p 8080:8080 -p 8025:8025 \
  -v kiss-mail-data:/data \
  -e KISS_MAIL_DOMAIN=mail.example.com \
  -e KISS_MAIL_WEB_BIND=0.0.0.0 \
  ghcr.io/pegasusheavy/kiss-mail:latest

# Create admin user
docker exec kiss-mail kiss-mail add admin yourpassword --role superadmin

# View logs
docker logs -f kiss-mail

Build Locally (Optional)

# Using Docker Hardened Images (requires Docker Hub login for dhi.io)
docker login dhi.io
docker build -t kiss-mail .

# Or using standard Alpine (no login required)
docker build -f Dockerfile.alpine -t kiss-mail .

Docker Compose

# Start all services
docker-compose up -d

# With ClamAV antivirus
docker-compose --profile antivirus up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Container Environment Variables

Kubernetes

Using Kustomize

# Deploy
kubectl apply -k deploy/kubernetes/

# Check status
kubectl get pods -n kiss-mail

# Port forward for local access
kubectl port-forward svc/kiss-mail 8080:8080 -n kiss-mail

Using Helm

# Install
helm install kiss-mail deploy/helm/kiss-mail \
  --namespace kiss-mail \
  --create-namespace \
  --set domain=mail.example.com

# With ingress
helm install kiss-mail deploy/helm/kiss-mail \
  --namespace kiss-mail \
  --create-namespace \
  --set domain=mail.example.com \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=mail.example.com

# With external LoadBalancer
helm install kiss-mail deploy/helm/kiss-mail \
  --namespace kiss-mail \
  --create-namespace \
  --set externalService.enabled=true

# Upgrade
helm upgrade kiss-mail deploy/helm/kiss-mail --namespace kiss-mail

# Uninstall
helm uninstall kiss-mail --namespace kiss-mail

Cloud Deployment

All cloud deployments use Docker containers pulled from ghcr.io/pegasusheavy/kiss-mail:latest.

One-Click Install (Any VPS)

SSH into your server and run:

curl -fsSL https://raw.githubusercontent.com/pegasusheavy/kiss-mail/main/deploy/scripts/install.sh | sudo bash

This installs Docker, pulls the container image, and starts KISS Mail automatically.

Works on Ubuntu, Debian, CentOS, Rocky Linux, Amazon Linux, Fedora, and more.

Cloud Provider Comparison

All providers deploy the same Docker container:

Quick Deploy (Terraform)

# Choose your provider
cd deploy/aws          # or gcp, azure, digitalocean, linode, vultr, hetzner

# Configure
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars

# Deploy (pulls Docker container automatically)
terraform init
terraform apply

Generic Cloud-Init

For any cloud provider (OVH, Scaleway, Oracle, UpCloud, etc.):

1. Copy deploy/generic/cloud-init.yml
2. Edit the config section with your domain
3. Create VM with Ubuntu 22.04 and paste as user-data
4. Wait 2-5 minutes (installs Docker and pulls container)

What Gets Deployed

All deployment methods create the same setup:

• Docker installed and configured
• KISS Mail container running with auto-restart
• Nginx reverse proxy for web admin
• Firewall rules for mail ports
• Data persisted in /opt/kiss-mail/data

DNS Configuration

After deploying, configure these DNS records:

A     mail.yourdomain.com         YOUR_SERVER_IP
MX    yourdomain.com       10     mail.yourdomain.com
TXT   yourdomain.com              "v=spf1 ip4:YOUR_SERVER_IP -all"

Enable HTTPS

SSH into your server and run:

sudo certbot --nginx -d mail.yourdomain.com

Upgrade

curl -fsSL https://raw.githubusercontent.com/pegasusheavy/kiss-mail/main/deploy/scripts/upgrade.sh | sudo bash

Uninstall

curl -fsSL https://raw.githubusercontent.com/pegasusheavy/kiss-mail/main/deploy/scripts/uninstall.sh | sudo bash

# Keep data
curl -fsSL ... | sudo bash -s -- --keep-data

Features

• ✅ SMTP server (send/receive)
• ✅ IMAP server (read emails)
• ✅ POP3 server (download emails)
• ✅ Zero-Knowledge Encryption (ProtonMail-style)
• ✅ Web Admin Dashboard (Tailwind CSS)
• ✅ Remote CLI & REST API
• ✅ SSO authentication (1Password, Google, Microsoft, Okta, Auth0)
• ✅ LDAP authentication (Active Directory, OpenLDAP)
• ✅ Groups / distribution lists
• ✅ AI spam detection (Bayesian classifier + rules)
• ✅ Anti-virus scanning (built-in + ClamAV)
• ✅ User management
• ✅ Zero configuration
• ✅ Single binary

Email Encryption

KISS Mail automatically encrypts emails at rest using ProtonMail-style zero-knowledge encryption.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                     User Registration                           │
│  Password → Argon2 → Key Encryption Key (KEK)                  │
│  Generate X25519 keypair                                        │
│  Private key encrypted with KEK → stored                        │
│  Public key → stored (unencrypted)                              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     Email Encryption                            │
│  1. Generate random symmetric key (per email)                   │
│  2. Encrypt email body with ChaCha20-Poly1305                   │
│  3. Encrypt symmetric key with recipient's public key           │
│  4. Store: encrypted_key + nonce + ciphertext                   │
└─────────────────────────────────────────────────────────────────┘

Security Properties

Configuration

Startup Banner

Security:
  Anti-spam   ✓ Rules + AI (1234 patterns learned)
  Anti-virus  ✓ Built-in
  Encryption  ✓ X25519-ChaCha20-Poly1305 (5 keys)

Key Management

• Keys are automatically generated when a user is created
• Private keys are encrypted with the user's password
• Password changes re-encrypt the private key
• Keys are stored in keys.json in the data directory

AI Spam Detection

KISS Mail uses a hybrid spam detection system:

How It Works

1. Bayesian Classifier - Self-learning AI that:

   • Learns from spam/ham patterns
   • Extracts 50+ features (URLs, caps, urgency words, etc.)
   • Persists learned data to disk
   • Seeds with common spam patterns on first run

2. Rule-based Scoring - Traditional heuristics:

   • Rate limiting
   • Keyword detection
   • Header analysis
   • Suspicious URL patterns

3. Combined Decision - Weighted average of AI + rules (60%/40% default)

What You'll See

Security:
  Anti-spam   ✓ Rules + AI (847 patterns learned)
  Anti-virus  ✓ ClamAV 1.0.0

Self-Learning

The classifier improves over time as it sees more emails. Patterns are saved to mail_data/spam_classifier.json.

Groups / Distribution Lists

Create email groups to send messages to multiple users at once.

Quick Start

# Create a group (auto-generates email: developers@yourdomain.com)
kiss-mail group-add developers

# Or specify a custom email
kiss-mail group-add team team-all@example.com

# Add members
kiss-mail group-add-member developers alice
kiss-mail group-add-member developers bob

# List groups
kiss-mail groups

# View group details
kiss-mail group-info developers

How It Works

When an email is sent to a group address (e.g., developers@yourdomain.com), it's automatically expanded and delivered to all group members.

Group Features

CLI Commands

groups                           # List all groups
group-add <name> [email]         # Create group
group-del <name>                 # Delete group
group-info <name>                # Show details
group-add-member <group> <user>  # Add user
group-rm-member <group> <user>   # Remove user

Data Storage

Groups are persisted to mail_data/groups.json.

LDAP Integration

Authenticate users against LDAP directories (Active Directory, OpenLDAP, etc.).

Quick Setup

# Set LDAP server URL to enable
export LDAP_URL=ldap://ldap.example.com:389
export LDAP_BASE_DN=dc=example,dc=com

# Optional: Service account for user searches
export LDAP_BIND_DN=cn=admin,dc=example,dc=com
export LDAP_BIND_PASSWORD=secret

# Start server
kiss-mail

Test LDAP Connection

# Test connection
kiss-mail ldap-test

# Test authentication
kiss-mail ldap-auth username password

# Search for user
kiss-mail ldap-search username

Configuration Options

Active Directory Example

export LDAP_URL=ldap://dc.example.com:389
export LDAP_BASE_DN=dc=example,dc=com
export LDAP_BIND_DN=cn=service,cn=users,dc=example,dc=com
export LDAP_BIND_PASSWORD=secret
export LDAP_USER_FILTER="(&(objectClass=user)(sAMAccountName={username}))"
export LDAP_USER_DN_TEMPLATE="{username}@example.com"

How It Works

1. User attempts to login via IMAP/POP3
2. If LDAP is configured, authenticate against LDAP first
3. On success, auto-create local mailbox if needed
4. If LDAP fails and fallback is enabled, try local auth
5. Local mailboxes store emails, LDAP provides authentication

Startup Banner

Directory:
  LDAP        ✓ ldap://ldap.example.com:389 (TLS)

SSO Integration

Authenticate users via Single Sign-On providers using OAuth2/OIDC.

Supported Providers

Quick Setup (Google Example)

export GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
export GOOGLE_CLIENT_SECRET=your-client-secret
kiss-mail

App Passwords

Since email clients (Thunderbird, Outlook, etc.) don't support OAuth2, generate app passwords:

# Generate app password for a user
kiss-mail app-password alice "Thunderbird"
# Output: abcd-efgh-jkmn-pqrs-tuvw-xyz1

# List app passwords
kiss-mail app-passwords alice

# Revoke app password
kiss-mail app-pass-revoke alice <password-id>

Use the generated password in your mail client instead of your SSO password.

CLI Commands

kiss-mail sso-status                    # Show SSO configuration
kiss-mail app-password <user> [label]   # Generate app password
kiss-mail app-passwords <user>          # List app passwords  
kiss-mail app-pass-revoke <user> <id>   # Revoke app password

Startup Banner

Identity:
  LDAP        ✓ ldap://ldap.example.com:389
  SSO         ✓ Google + app passwords

Web Admin Dashboard

A simple, beautiful web interface for managing your mail server.

Access

http://localhost:8080/admin

Login with any admin user credentials.

Features

• Dashboard - Server overview, stats, quick actions
• Users - Create, edit, delete users; manage roles and status
• Groups - Create distribution lists, manage members

Screenshots

The interface uses Tailwind CSS for a clean, modern design:

• Clean navigation with active state highlighting
• Responsive tables for users and groups
• Form validation and flash messages
• Session-based authentication

Configuration

Startup Banner

Servers:
  SMTP  →  localhost:2525
  IMAP  →  localhost:1143
  POP3  →  localhost:1100
  Web   →  http://localhost:8080/admin

Remote Administration

Manage the server remotely via CLI or REST API.

Enable Remote API

Set an API key to enable remote access:

export KISS_MAIL_API_KEY=your-secret-key
kiss-mail

The API server starts on port 8025 by default:

Servers:
  SMTP  →  localhost:2525
  IMAP  →  localhost:1143
  POP3  →  localhost:1100
  API   →  localhost:8025

Remote CLI Usage

# Using flags
kiss-mail --server mail.example.com:8025 --api-key your-secret-key list

# Short flags
kiss-mail -s localhost:8025 -k mykey status

# Using environment variables  
export KISS_MAIL_SERVER=mail.example.com:8025
export KISS_MAIL_API_KEY=your-secret-key
kiss-mail list
kiss-mail add bob password123
kiss-mail group-add developers

Supported Remote Commands

REST API Endpoints

The admin API also provides REST endpoints for programmatic access:

# Authentication
POST /api/auth/login     # Login with admin credentials
POST /api/auth/logout    # Logout

# Status
GET  /api/status         # Server status

# Users
GET  /api/users          # List users
POST /api/users          # Create user
GET  /api/users/:user    # Get user
PUT  /api/users/:user    # Update user
DELETE /api/users/:user  # Delete user

# Groups
GET  /api/groups         # List groups
POST /api/groups         # Create group
GET  /api/groups/:name   # Get group
DELETE /api/groups/:name # Delete group
POST /api/groups/:name/members           # Add member
DELETE /api/groups/:name/members/:user   # Remove member

# App Passwords
GET  /api/users/:user/app-passwords      # List app passwords
POST /api/users/:user/app-passwords      # Generate app password
DELETE /api/users/:user/app-passwords/:id # Revoke app password

# LDAP
GET  /api/ldap/status    # LDAP status
POST /api/ldap/test      # Test LDAP connection

# SSO  
GET  /api/sso/status     # SSO status

Example API Calls

# Get status
curl -H "Authorization: Bearer your-api-key" http://localhost:8025/api/status

# Create user
curl -X POST -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}' \
  http://localhost:8025/api/users

# List groups
curl -H "X-API-Key: your-api-key" http://localhost:8025/api/groups

Configuration

ClamAV Integration

KISS Mail automatically detects and uses ClamAV if available. No configuration needed!

Install ClamAV (optional)

# Debian/Ubuntu
sudo apt install clamav-daemon
sudo systemctl start clamav-daemon

# macOS
brew install clamav
clamd

# The server will auto-detect ClamAV at 127.0.0.1:3310

Configure ClamAV

# Use custom ClamAV address
CLAMAV_ADDRESS=192.168.1.100:3310 kiss-mail

# Disable ClamAV (use built-in only)
CLAMAV_ENABLED=false kiss-mail

When ClamAV is available, you'll see:

Security:
  Anti-spam   ✓ Enabled
  Anti-virus  ✓ ClamAV 1.0.0/26789/...

When ClamAV is not available, the built-in scanner is used:

Security:
  Anti-spam   ✓ Enabled
  Anti-virus  ✓ Built-in (ClamAV not found)

License

MIT