# Copilot Instructions: Mail List Manager (Postfix + SES + Web Interface)

## Architecture Overview

This is a containerized mailing list management system built around Postfix as an SMTP relay through Amazon SES. **Currently in Phase 1** with static configuration; **planned expansion** includes web frontend and SQL database for dynamic member management.

**Current Components (Phase 1):**
- `docker-compose.yaml`: Single-service orchestration with SES credentials
- `postfix/`: Complete Postfix container configuration  
- Static virtual aliases system for mailing list distribution

**Planned Architecture (Phase 2+):**
- Web frontend for list management (view/add/remove members)
- SQL database backend for member storage
- Dynamic Postfix configuration generation
- Multi-service Docker Compose setup

## Configuration Pattern

**Current (Static):** Environment variable substitution for secure credential management:

1. **Credentials Flow**: SES credentials passed via environment → `sasl_passwd.template` → runtime generation in `entrypoint.sh`
2. **Config Files**: Static configs (`main.cf`, `virtual_aliases.cf`) + dynamic SASL auth file
3. **Postfix Maps**: Hash databases generated at build time (virtual aliases) and runtime (SASL)

**Future (Dynamic):** Database-driven configuration:
- Member lists stored in SQL database
- Web interface for CRUD operations on members
- `virtual_aliases.cf` generated from database at runtime
- Postfix reload triggered by configuration changes

## Key Files and Their Roles

- `main.cf`: Core Postfix config - relay through SES, domain settings, security
- `sasl_passwd.template`: Template for SES authentication (uses `${SES_USER}:${SES_PASS}`)
- `virtual_aliases.cf`: Static email forwarding rules (one mailing list currently)
- `entrypoint.sh`: Runtime credential processing and Postfix startup

## Development Workflows

**Building and Running:**
```bash
docker-compose up --build    # Build and start mail server
docker-compose logs -f       # Monitor mail delivery logs
```

**Adding Mailing Lists (Current):**
1. Edit `virtual_aliases.cf` with new list → recipients mapping
2. Rebuild container (postmap runs at build time)
3. No restart needed for existing virtual alias changes

**Future Web Interface Workflow:**
1. Access web frontend at configured port
2. Use CRUD interface to manage mailing lists and members
3. Changes automatically update database and regenerate Postfix configs

**Testing Mail Delivery:**
```bash
# From inside container
echo "Test message" | mail -s "Subject" community@lists.sasalliance.org

# Check logs for SES relay status
docker-compose logs postfix | grep -E "(sent|bounced|deferred)"
```

## Security Considerations

- SES credentials exposed in docker-compose.yaml (consider using Docker secrets)
- SASL password file permissions set to 600 in entrypoint
- TLS encryption enforced for SES relay (`smtp_tls_security_level = encrypt`)
- Only localhost and configured hostname accepted for local delivery

## Configuration Conventions

- **Hostname Pattern**: `lists.sasalliance.org` for mailing lists, origin domain `sasalliance.org`
- **Virtual Aliases**: Simple format `listname@lists.domain → recipient1, recipient2`
- **SES Region**: EU West 2 (`email-smtp.eu-west-2.amazonaws.com`)
- **Port Mapping**: Standard SMTP port 25 exposed to host

## Common Modifications

**Adding Recipients to Existing List (Current):**
Edit `virtual_aliases.cf`, add comma-separated emails, rebuild container.

**New Mailing List (Current):**
Add line to `virtual_aliases.cf`: `newlist@lists.sasalliance.org recipients...`

**Credential Updates:**
Update `SES_USER`/`SES_PASS` in docker-compose.yaml, restart container.

## Migration Considerations

When implementing the web frontend and database backend:
- Preserve existing `community@lists.sasalliance.org` list during migration
- Consider migration script to import current virtual aliases into database
- Plan for zero-downtime deployment with database-driven config generation
- Web interface should validate email addresses and handle duplicate members