CastMail2List

CastMail2List is a lightweight, self-hosted mailing list application. It polls standard IMAP mailboxes for incoming messages, distributes them to subscribers, and provides a web interface for list management. No MTA configuration, no complex server setup — just point it at one or more IMAP accounts and go.

Why CastMail2List?

Compared to plain email forwarding:

• Subscriber management with a web UI and REST API
• Two list modes: broadcast (newsletters/announcements) and group (discussion lists)
• Sender authorization via allowed-sender lists or password-based authentication
• Automatic bounce detection
• Duplicate message prevention
• Per-list IMAP accounts — each list can use its own mailbox
• Message logs, delivery tracking, and rejection notifications

Compared to Mailman 3 or similar:

• Minimal dependencies — runs on Python 3.10+, SQLite, and any IMAP/SMTP provider
• No MTA integration required — works with any email provider that offers IMAP and SMTP
• Simple YAML-based configuration
• Hierarchical list support via nested lists (lists can subscribe to other lists)
• Easy to deploy on shared hosting (Uberspace natively supported) or as a container
• Single process, small footprint - suitable for personal use or small communities

CastMail2List is not a replacement for Mailman in large-scale or enterprise setups. It's designed for people who want mailing list functionality without the operational overhead of running a full mail server stack.

Features

• Broadcast mode — one-to-many distribution (newsletters, announcements). Only authorized senders can post.
• Group mode — many-to-many discussion lists with reply-to-list behavior.
• Web interface — manage lists, subscribers, messages, and delivery logs.
• REST API — programmatic subscriber management with API key authentication.
• IMAP-based — polls mailboxes on a configurable interval; no MTA hooks needed.
• Bounce handling — detects bounced messages and tracks per-subscriber bounce counts.
• Sender authorization — allowed-sender lists and/or password-in-address authentication.
• Rejection notifications — optionally notify senders when their message is rejected.
• Nested lists — lists can include other lists as subscribers for hierarchical distribution.
• Internationalization — UI available in English and German; extensible via standard gettext.
• Database migrations — schema changes handled automatically via Alembic/Flask-Migrate.

Requirements

• Python 3.10+
• Optional: sass. CastMail2List compiles its bundled SCSS to CSS on startup. If no system-wide sass binary is found on PATH, it automatically falls back to the bundled sass-embedded Python package, which downloads a pinned Dart Sass binary into the virtual environment on first run (cached afterward, no repeated downloads). Installing system sass is optional but avoids that one-time download, keeps the virtual environment smaller, and allows the user to define which version is being used.

Installation

From PyPI

pip install castmail2list

From source

git clone https://github.com/mxmehl/castmail2list.git
cd castmail2list
uv sync --no-dev

Quick start

1. Create a configuration file:

   cp config.example.yaml config.yaml
   

2. Edit config.yaml with your IMAP/SMTP credentials, database path, and other settings. See config.example.yaml for all available options.

3. Run the application:

   For production (using gunicorn as WSGI server):

   castmail2list --config config.yaml
   

   For development and admin commands (using Flask directly):

   castmail2list-cli --config config.yaml --debug
   

4. Access the web interface at http://localhost:2278 and log in with the credentials set in your configuration.

Run castmail2list --help or castmail2list-cli --help for all available options.

Configuration

CastMail2List is configured via a YAML file. See config.example.yaml for the full reference.

The configuration file is validated against a JSON schema (castmail2list/config_schema.json) to ensure all required fields are present and correctly formatted. This is the single source of truth for configuration options, their types, and default values. The application will fail to start if the configuration file is invalid.

Maintenance

Clean up sent emails

Over time, the IMAP Sent folder can grow large, especially for lists with many subscribers. Use the --cleanup imap-sent command to permanently delete sent emails older than a given threshold:

# Delete all sent emails older than 7 days (dry run first)
castmail2list-cli --config config.yaml --cleanup imap-sent --older-than 7days --dry

# Actually delete them
castmail2list-cli --config config.yaml --cleanup imap-sent --older-than 7days

Supported duration formats (case-insensitive): 1hour / 24hours, 1day / 7days, 1month / 3months. The --dry flag logs what would be deleted without making any changes.

Documentation

• Mailing list modes and headers — how broadcast and group modes differ
• Sender authorization — controlling who can send to a list
• API documentation — REST API for subscriber management
• Contributing — development setup, testing, and translation guide

Contributing

Contributions and translations are welcome! See CONTRIBUTING.md for development setup, testing, and translation guidelines.

Copyright and Licensing

This project is mainly licensed under the Apache License 2.0, copyrighted by Max Mehl.

It also contains files from different copyright holders and under different licenses. As the project follows the REUSE best practices, you can find the according information for each individual file.