rmail — Getting Started

Prerequisites

Python 3.8 or later
POSIX operating system (Linux, macOS) — required for fcntl.flock()
No third-party packages — pure stdlib only
Ports 25, 465, 587, 143, 993, 9002, 9003 available (or configure alternates)
openssl CLI available for auto-generated TLS certificates (optional but recommended)

Binding to ports below 1024 (25, 143, 465, 587, 993) requires root or CAP_NET_BIND_SERVICE on Linux. Run as root or use setcap cap_net_bind_service=+ep $(which python3).

Installation

From source

git clone https://github.com/retoor/rmail
cd rmail

No virtual environment or package installation required. rmail runs directly from the cloned directory.

Configuration

Generate default config

python run.py init

This writes config.json to the current directory with all defaults. Open it and set at minimum:

{
  "hostname": "mail.example.com",
  "domains": ["example.com"],
  "mail_root": "./mailstore"
}

hostname must match the server's actual FQDN. It appears in SMTP banners, EHLO responses, relay DSN bounces, and autoconfig XML.

TLS

If tls.cert_file is null (the default), rmail auto-generates a self-signed certificate under {mail_root}/tls/ on first start using openssl. To use a CA-signed certificate:

{
  "tls": {
    "cert_file": "/etc/ssl/certs/mail.pem",
    "key_file": "/etc/ssl/private/mail.key"
  }
}

Creating a User

python run.py user add alice example.com

User data is stored under {mail_root}/domains/{domain}/users/{username}/. Default mailboxes INBOX, Sent, Drafts, and Trash are created automatically.

Starting the Server

python run.py

Specify a config path explicitly if needed:

python run.py /etc/rmail/config.json

On startup, rmail logs all active ports:

rmail server started - hostname: mail.example.com
  SMTP:       0.0.0.0:25
  Submission: 0.0.0.0:587
  SMTPS:      0.0.0.0:465 (implicit TLS)
  IMAP:       0.0.0.0:143
  IMAPS:      0.0.0.0:993 (implicit TLS)
  Exchange:   0.0.0.0:9002
  Domains:    example.com
  Delivery:   4 workers
  Relay:      enabled, 2 workers

Install as a systemd service

sudo python run.py install

Creates /etc/systemd/system/rmail.service with Restart=on-failure. Manage with standard systemctl commands.

sudo systemctl start rmail
sudo systemctl enable rmail
sudo systemctl status rmail

To remove the service:

sudo python run.py uninstall

First Message

Send a test message to a local user using Python's smtplib:

import smtplib

s = smtplib.SMTP("127.0.0.1", 587, timeout=5)
s.ehlo("test")
s.login("alice@example.com", "password")
s.sendmail(
    "alice@example.com",
    ["alice@example.com"],
    "From: alice@example.com\r\nTo: alice@example.com\r\nSubject: Hello\r\n\r\nFirst message.\r\n"
)
s.quit()

Run diagnostics

The built-in 8-phase diagnostic tool verifies all server components end-to-end:

sudo python run.py diagnose

A clean run produces 130+ passing checks covering configuration, user management, storage, SMTP, delivery, IMAP, Exchange API, and relay.