| name | mailman |
| description | Guidance for setting up mailing list servers with Postfix and Mailman3. This skill should be used when configuring email infrastructure, integrating Mailman3 with Postfix MTA, creating mailing lists, or troubleshooting mail delivery issues. |
Mailman - Mailing List Server Setup
Overview
This skill provides guidance for setting up and configuring mailing list servers using Postfix (MTA) and Mailman3. It covers proper integration patterns, configuration best practices, and verification strategies to avoid common pitfalls.
Approach
Phase 1: Documentation Review
Before making any configuration changes:
- Read Mailman3's official documentation on Postfix integration
- Understand the
[mta] section configuration in mailman.cfg
- Identify the native integration mechanisms (postfix_lmtp, postfix_domains)
- Review existing configuration files to understand current state
Phase 2: Configuration Architecture
The proper integration between Postfix and Mailman3 involves:
-
Mailman3 MTA Configuration (mailman.cfg):
- Configure
[mta] section with proper incoming and outgoing settings
- Set
postfix_map_exe for automatic alias generation
- Configure LMTP listener settings
-
Postfix Integration:
- Configure
main.cf to use mailman-generated transport maps
- Set up virtual alias maps pointing to mailman's generated files
- Avoid creating custom transport definitions when native integration exists
-
LMTP Delivery:
- Verify LMTP port configuration (default: 8024)
- Ensure Postfix can communicate with Mailman's LMTP server
Phase 3: Implementation Order
Execute configuration in this order:
- Configure Mailman3's
mailman.cfg for MTA integration
- Restart Mailman3 services to apply configuration
- Verify Mailman generates transport/alias files
- Configure Postfix to use Mailman-generated maps
- Reload Postfix configuration
- Create mailing lists
- Test mail delivery
Verification Strategies
Pre-Implementation Verification
- Check if services are running:
systemctl status mailman3 and systemctl status postfix
- Verify LMTP port is listening:
ss -tlnp | grep 8024
- Check Mailman's configured MTA:
mailman conf | grep -A10 '\[mta\]'
Configuration Verification
- Validate Postfix configuration:
postfix check
- Test Postfix configuration syntax before reload
- Verify Mailman-generated files are populated (not empty)
- Check file permissions on transport maps
Post-Implementation Verification
- Send test emails and verify delivery
- Check mail logs:
journalctl -u postfix and journalctl -u mailman3
- Verify list creation persisted in database
- Test service survival after restart
Database Verification
- Verify list creation persisted: check with
mailman lists command
- Understand Mailman3's transaction model for list operations
- Ensure database commits occur properly
Common Pitfalls
1. Empty Alias/Transport Files
Symptom: Mailman-generated postfix files (postfix_lmtp, postfix_domains) are empty.
Cause: Improper [mta] section configuration in mailman.cfg.
Investigation: Check [mta] configuration settings rather than creating workaround scripts.
2. Custom Transport Instead of Native Integration
Anti-pattern: Creating custom mailman: transport in master.cf and manual alias scripts.
Problem: Duplicates built-in functionality, breaks when lists change, requires manual intervention.
Solution: Use Mailman3's native postfix_map_exe configuration for automatic alias generation.
3. List Creation Not Persisting
Symptom: List created via API/CLI but doesn't appear after service restart.
Cause: Database transaction not committed properly.
Investigation: Check Mailman's transaction handling, verify database configuration.
4. Malformed Configuration Sections
Anti-pattern: Adding non-standard sections like [styles] or [style.legacy-default] with settings that don't follow Mailman3's schema.
Problem: Settings like subscription_policy should be set on lists, not as style definitions.
Solution: Consult official schema documentation before adding configuration sections.
5. LMTP Port Mismatch
Symptom: Mail delivery fails with connection refused.
Cause: Postfix configured to connect to wrong LMTP port.
Verification: Check Mailman's actual LMTP port vs Postfix transport configuration.
6. Missing Automatic Synchronization
Symptom: New lists don't receive mail without manual intervention.
Cause: Missing postfix_maps configuration for automatic regeneration.
Solution: Configure Mailman to automatically update Postfix maps when lists change.
Debugging Workflow
When mail delivery fails:
- Trace the mail path: Check Postfix logs for delivery attempts
- Verify transport lookup:
postmap -q listname@domain /path/to/transport
- Test LMTP directly:
telnet localhost 8024
- Check Mailman logs: Look for LMTP connection errors
- Verify list exists:
mailman lists -d domain
Key Configuration Files
| File | Purpose |
|---|
/etc/mailman3/mailman.cfg | Main Mailman3 configuration |
/etc/postfix/main.cf | Postfix main configuration |
/etc/postfix/master.cf | Postfix service definitions |
/var/lib/mailman3/data/postfix_lmtp | Mailman-generated LMTP transport map |
/var/lib/mailman3/data/postfix_domains | Mailman-generated relay domains |
Testing Checklist
Before declaring success:
