Mail List Manager

A containerized mailing list management system built around Postfix as an SMTP relay through Amazon SES.

Architecture

Current (Phase 1): Static configuration with environment-based credentials

• Postfix container configured as SES relay
• Static virtual aliases for mailing list distribution
• Environment variable configuration for security

Planned (Phase 2+): Web interface with SQL backend

• Web frontend for list management (view/add/remove members)
• SQL database for member storage
• Dynamic Postfix configuration generation

Quick Start

1. Copy the environment template:

   cp .env.example .env
   

2. Edit .env with your SES credentials and configuration:

   # Required: Your SES credentials
   SES_USER=your_ses_access_key
   SES_PASS=your_ses_secret_key
   
   # Optional: SMTP configuration (defaults to EU West 2)
   SMTP_HOST=email-smtp.eu-west-2.amazonaws.com
   SMTP_PORT=587
   

3. Build and start the mail server:

   docker-compose up --build
   

4. Test mail delivery:

   # From inside container
   docker-compose exec postfix bash
   echo "Test message" | mail -s "Subject" community@lists.sasalliance.org
   
   # Check logs
   docker-compose logs -f postfix
   

Configuration

Adding Mailing Lists (Current)

Edit postfix/virtual_aliases.cf:

newlist@lists.sasalliance.org   recipient1@domain.com, recipient2@domain.com

Then rebuild the container:

docker-compose up --build

Domain Configuration

The system is configured for:

• Hostname: lists.sasalliance.org (mailing lists)
• Origin Domain: sasalliance.org
• SES Region: EU West 2 (configurable via SMTP_HOST)

Security

• SES credentials are stored in .env (git-ignored)
• SASL password files have restricted permissions (600)
• TLS encryption enforced for SES relay
• Only localhost and configured hostname accepted for local delivery

Development

Project Structure

├── docker-compose.yaml          # Service orchestration
├── .env                        # Environment configuration (not in git)
├── postfix/
│   ├── Dockerfile             # Postfix container build
│   ├── entrypoint.sh          # Runtime configuration processing
│   ├── main.cf.template       # Postfix main configuration template
│   ├── sasl_passwd.template   # SES authentication template
│   └── virtual_aliases.cf     # Static mailing list definitions
└── .github/
    └── copilot-instructions.md # AI agent guidance

Environment Variables

• SES_USER: AWS SES access key ID
• SES_PASS: AWS SES secret access key
• SMTP_HOST: SMTP server hostname (default: email-smtp.eu-west-2.amazonaws.com)
• SMTP_PORT: SMTP server port (default: 587)

Debugging

Monitor mail delivery:

# View all logs
docker-compose logs -f

# Filter for delivery status
docker-compose logs postfix | grep -E "(sent|bounced|deferred)"

# Check Postfix queue
docker-compose exec postfix postqueue -p

Roadmap

• Web frontend for mailing list management
• SQL database backend for member storage
• Dynamic configuration generation from database
• Multi-service Docker Compose architecture
• Migration tools for static → dynamic configuration

License

MIT License - see LICENSE file for details.