mailman

name	mailman
description	Guidance for setting up and configuring mailing list servers with Postfix and Mailman3. This skill should be used when tasks involve configuring email servers, mailing list management, LMTP integration, or mail delivery pipelines. Applies to tasks requiring Postfix-Mailman integration, subscription workflows, or email broadcast functionality.

Mailman

Overview

This skill provides guidance for configuring mailing list servers using Postfix and Mailman3. It covers the complete mail delivery pipeline including inbound mail handling, LMTP integration, subscription workflows, and outbound broadcast delivery to list subscribers.

Architecture Understanding

Before configuring, understand the bidirectional mail flow architecture:

Inbound Flow (Mail INTO Mailman)

1. External mail arrives at Postfix
2. Postfix routes list addresses to Mailman via LMTP
3. Mailman processes: subscriptions, unsubscriptions, and posts

Outbound Flow (Mail OUT from Mailman)

1. Mailman processes incoming posts
2. Mailman generates individual messages for each subscriber
3. Mailman sends via Postfix back to subscriber mailboxes
4. Messages arrive in subscriber local mailboxes (e.g., /var/mail/)

Critical Insight: Both directions must work. A common failure mode is configuring only the inbound path while neglecting outbound delivery to subscribers.

Verification Strategy

Mandatory Pre-Completion Verification

Before declaring any mailing list setup complete, verify ALL three core functions:

1. Join/Subscribe: User can join the mailing list
2. Post/Broadcast: Messages sent to the list reach ALL subscribers
3. Leave/Unsubscribe: User can leave the mailing list

End-to-End Testing Approach

To verify the complete mail flow:

1. Test subscription

   • Send join request to list-join@domain
   • Verify confirmation arrives
   • Complete subscription process

2. Test broadcast delivery (most commonly missed)

   • Send a message to list@domain
   • Check EACH subscriber's mailbox for delivery
   • Verify the message content is intact

3. Test unsubscription

   • Send leave request to list-leave@domain
   • Verify confirmation and removal

Log Analysis Checkpoints

Regularly inspect logs during configuration:

• Postfix logs: /var/log/mail.log or journalctl -u postfix
• Mailman logs: /var/log/mailman3/ or check mailman's configured log directory
• LMTP connection logs for both directions

Common Configuration Points

Postfix Configuration Areas

Key files to examine and configure:

• /etc/postfix/main.cf - Main configuration
• /etc/postfix/master.cf - Service definitions
• Transport maps for routing to Mailman
• Virtual/relay domain configuration

Mailman3 Configuration Areas

Key areas to verify:

• LMTP runner configuration (host and port)
• MTA integration settings
• Pipeline runners for processing posts
• Outbound mail configuration

Integration Points to Verify

1. LMTP Connection: Confirm Mailman's LMTP runner is listening on the configured port
2. Transport Maps: Ensure Postfix routes list addresses correctly
3. Domain Handling: Verify how list domains interact with mydestination and relay_domains
4. Outbound Runner: Confirm Mailman's "out" runner sends messages back through Postfix

Common Pitfalls

Domain Configuration Conflicts

When the list domain is in Postfix's mydestination, Postfix treats ALL addresses at that domain as local. This can conflict with mailing list routing. Solutions include:

• Using transport_maps to override for list addresses
• Careful configuration of virtual domains
• Verifying the routing precedence

LMTP Verification Gaps

A common mistake is assuming LMTP works for all message types because subscription requests succeed. Posts may fail separately. To verify:

• Check that the LMTP port is actually listening
• Test with actual post messages, not just subscription requests
• Trace a post message through the complete pipeline

Incomplete Outbound Configuration

Mailman must send mail back to subscribers. Verify:

• The "out" runner is active and processing
• Mailman can connect to Postfix for sending
• Subscriber addresses resolve correctly
• Messages actually appear in subscriber mailboxes

Premature Success Declaration

Never declare success based on:

• A single test passing
• Only subscription tests working
• Automated tests that may not cover all functionality

Always manually verify the broadcast functionality before completion.

Debugging Approach

When mail delivery fails:

1. Trace the message path

   • Where does the message enter the system?
   • Does it reach Mailman's LMTP?
   • Does Mailman process it?
   • Does Mailman attempt outbound delivery?
   • Does Postfix accept the outbound message?
   • Does it reach the subscriber mailbox?

2. Check queue directories

   • Postfix queue: mailq or postqueue -p
   • Mailman queues: Check configured queue directories

3. Verify service status

   • All Mailman runners active
   • Postfix accepting connections
   • LMTP port listening

4. Examine logs between each step

   • Do not restart services repeatedly without checking logs
   • Each restart should be followed by log examination

Incremental Verification Process

Configure and verify in stages:

1. Stage 1: Basic Postfix mail delivery (local mail works)
2. Stage 2: Mailman installation and basic configuration
3. Stage 3: LMTP connection (Postfix to Mailman)
4. Stage 4: Subscription flow (join/leave)
5. Stage 5: Broadcast flow (post to all subscribers)
6. Stage 6: Full integration test with multiple subscribers

Do not proceed to the next stage until the current stage is verified working.