General Information

• Introduction to GNU Mailman
• PantherList Email Addresses
• Administrative Roles
• PantherList Web Pages
• Basic Architectural Overview
• PantherList Configuration Pages

Categories

• General Options
• Passwords
• Language Options
• Membership Management
• Non-digest Options
• Digest Options
• Privacy Options
• Bounce Processing
• Archiving Options
• Mail/News Gateway

Introduction to GNU Mailman

List Email Addresses 

Administrative Roles

There are two primary administrative roles for each mailing list, a list owner and a list moderator. A list owner is allowed to change various settings of the list, such as the privacy and archiving policies, the content filtering settings, etc. The list owner is also allowed to subscribe or invite members, unsubscribe members, and change any member's subscription options.

The list moderator on the other hand, is only allowed to approve or reject postings and subscription requests. The list moderator can also do things like clear a member's moderation flag, or add an address to a list of approved non-member posters.

Normally, the list owner and list moderator are the same person. In fact, the list owner can always do all the tasks a list moderator can do. Access to both the owner's configuration pages, and the moderation pages are protected by the same password. However, if the list owner wants to delegate posting and subscription approval authority to other people, a separate list moderator password can be set, giving moderators access to the approval pages, but not the configuration pages. In this setup, list owners can still moderate the list, of course.

In the sections that follow, we'll often use the terms list owner and list administrator interchangeably, meaning both roles. When necessary, we'll distinguish the list moderator explicitly.

List Web Pages

Every mailing list is also accessible by a number of web pages. Note that the exact urls is configurable by the site administrator, so they may be different than what's described below. We'll describe the most common default configuration, but check with your site administrator or hosting service for details.

Mailman provides a set of web pages that list members use to get information about the list, or manage their membership options. There are also list archive pages, for browsing an online web-based archive of the list traffic. These are described in more detail in the GNU Mailman user's manual.

Mailman also provides a set of pages for configuring an individual list, as well as a set of pages for disposing of posting and subscription requests.

For a mailing list called mylist hosted at the domain lists.example.com, you would typically access the administrative pages by going to http://lists.example.com/mailman/admin/mylist. The first time you visit this page, you will be presented with a login page, asking for the list owner's password. When you enter the password, Mailman will store a session cookie in your browser, so you don't have to re-authenticate for every action you want to take. This cookie is stored only until you exit your browser.

To access the administrative requests page, you'd visit http://lists.example.com/mailman/admindb/mylist (note the admindb url as opposed to the admin url). Again, the first time you visit this page, you'll be presented with a login page, on which you can enter either the list moderator password or the list owner password. Again, a session cookie is dropped in your browser. Note also that if you've previously logged in as the list owner, you do not need to re-login to access the administrative requests page.

Basic Architectural Overview

This section will outline the basic architecture of GNU Mailman, such as how messages are processed by the sytem. Without going into lots of detail, this information will help you understand how the configuration options control Mailman's functionality.

When mail enters the system from your mail server, it is dropped into one of several Mailman queues depending on the address the message was sent to. For example, if your system has a mailing list named mylist and your domain is example.com, people can post messages to your list by sending them to mylist@example.com. These messages will be dropped into the incoming queue, which is also colloquially called the moderate-and-munge queue. The incoming queue is where most of the approval process occurs, and it's also where the message is prepared for sending out to the list membership.

There are separate queues for the built-in archiver, the bounce processor, the email command processor, as well as the outgoing email and news queues. There's also a queue for messages generated by the Mailman system. Each of these queues typically has one queue runner (or ``qrunner'') that processes messages in the queue. The qrunners are idle when there are no messages to process.

Every message in the queues are represented by two files, a message file and a metadata file. Both of these files share the same base name, which is a combination of a unique hash and the Unix time that the message was received. The metadata file has a suffix of .db and the message file has a suffix of either .msg if stored in plain text, or .pck if stored in a more efficient internal representation¹.

As a message moves through the incoming queue, it performs various checks on the message, such as whether it matches one of the moderation criteria, or contains disallowed MIME types. Once a message is approved for sending to the list membership, the message is prepared for sending by deleting, adding, or changing message headers, adding footers, etc. Messages in the incoming queue may also be stored for appending to digests.

PantherList Configuration Pages

After logging into the list configuration pages, you'll see the configuration options for the list, grouped in categories. All the administrative pages have some common elements. In the upper section, you'll see two columns labeled ``Configuration Categories''. Some categories have sub-categories which are only visible when you click on the category link. The first page you see after logging in will be the ``General Options'' category. The specific option settings for each category are described below.

On the right side of the top section, you'll see a column labeled ``Other Administrative Activities''. Here you'll find some other things you can do to your list, as well as convenient links to the list information page and the list archives. Note the big ``Logout'' link; use this if you're finished configuring your list and don't want to leave the session cookie active in your browser.

Below this common header, you'll find a list of this category's configuration variables, arranged in two columns. In the left column is a brief description of the option, which also contains a ``details'' link. For many of the variables, more details are available describing the semantics of the various available settings, or information on the interaction between this setting and other list options. Clicking on the details link brings up a page which contains only the information for that option, as well as a button for submitting your setting, and a link back to the category page.

On the right side of the two-column section, you'll see the variable's current value. Some variables may present a limited set of values, via radio button or check box arrays. Other variables may present text entry boxes of one or multiple lines. Most variables control settings for the operation of the list, but others perform immediate actions (these are clearly labeled).

At the bottom of the page, you'll find a ``Submit'' button and a footer with some more useful links and a few logos. Hitting the submit button commits your list settings, after they've been validated. Any invalid values will be ignored and an error message will be displayed at the top of the resulting page. The results page will always be the category page that you submitted.

General Options

The General Options category is where you can set a variety of variables that affect basic behavior and public information. In the descriptions that follow, the variable name is given first, along with an overview and a description of what that variable controls.

Passwords

Language Options

Mailman is multilingual and internationalized, meaning you can set up your list so that members can interact with it in any of a number of natural languages. Of course, Mailman won't translate list postings. :)

However, if your site administrator has enabled its support, you can set your list up to support any of about two dozen languages, such as German, Italian, Japanese, or Spanish. Your list members can then choose any of your supported languages as their preferred language for interacting with the list. Such things as their member options page will be displayed in this language. Each mailing list also has its own preferred language which is the language the list supports if no other language context is known.

These variables control the language settings for your mailing list:

preferred_language

This is the list's preferred language, which is the language that the list administrative pages will be displayed in. Also any messages sent to the list owners by Mailman will be sent in this language. This option is presented as a drop-down list containing the language enabled in the available_languages variable.

available_languages

This set of checkboxes contains all the natural languages that your site administrator has made available to your mailing lists. Select any language that you'd either like your members to be able to view the list in, or that you'd like to be able to use in your list's preferred_language variable.

encode_ascii_prefixes

If your mailing list's preferred language uses a non-ASCII character set and the subject_prefix contains non-ASCII characters, the prefix will always be encoded according to the relevant standards. However, if your subject prefix contains only ASCII characters, you may want to set this option to Never to disable prefix encoding. This can make the subject headers slightly more readable for users with mail readers that don't properly handle non-ASCII encodings.

Note however, that if your mailing list receives both encoded and unencoded subject headers, you might want to choose As needed. Using this setting, Mailman will not encode ASCII prefixes when the rest of the header contains only ASCII characters, but if the original header contains non-ASCII characters, it will encode the prefix. This avoids an ambiguity in the standards which could cause some mail readers to display extra, or missing spaces between the prefix and the original header.

To the top

Membership Management

The Membership Management category is unlike the other administrative categories. It doesn't contain configuration variables or list settings. Instead, it presents a number of pages that allow you to manage the membership of you list. This includes pages for subscribing and unsubscribing members, and for searching for members, and for changing various member-specific settings.

More details on membership management are described in the Membership Management section.

Non-digest Options

Mailman delivers messages to users via two modes. List members can elect to receive postings in bundles call digests one or a few times a day, or they can receive messages immediately whenever the message is posted to the list. This latter delivery mode is also called non-digest delivery. There are two administrative categories available for separately controlling digest and non-digest delivery. You can even disable one or the other forms of delivery (but not both).

Both kinds of delivery can have list-specific headers and footers added to them which can contain other useful information you want your list members to see. For example, you can include instructions for unsubscribing, or a url to the lists digest, or any other information.

Non-digest deliveries can also be personalized which means certain parts of the message can contain information tailored to the member receiving the message. For example, the To: header will contain the address of the member when deliveries are personalized. Footers and headers can contain personalized information as well, such as a link to the individual user's options page.

In addition, personalized messages will contain extra information that Mailman can use to unambiguously track bounces from members. Ordinarily, Mailman does some pattern recognition on bounce messages to determine list members whose addresses are no longer valid, but because of the vagaries of mail systems, and the countless forwards people can put in place, it's often the case that bounce messages don't contain any useful information in them. Personalized messages avoid this problem by encoding information in certain headers that unambiguously identify the recipient of a message. If that message bounces, Mailman will know exactly which member it was intended for.

Note that because personalization requires extra system resources, it must be enabled by the site administrator before you can choose it.

Here are the variables which control non-digest delivery:

nondigestable

This option controls whether members can receive immediate delivery or not. If not, they will be forced to receive messages in digests. You can't disable non-digest delivery if digests are already disabled.

personalize

This option turns on message personalization.

msg_header

This text box lets you enter information that will be included in the header of every non-digest message sent through the list.

See below for more information on what can go in the headers and footers. If you leave this text box empty, no header will be added.

msg_footer

Just like with the header, you can add a footer to every message. The same rules apply to footers as apply to headers.

Headers and footers can contain any text you want. For non-English lists, the headers and footers can contain any character in the character set of the list's preferred language. The headers and footers can also contain substitution variables which Mailman will fill in with information taken from the mailing list. These substitutions are in Python string interpolation format, where something like %(list_name)s is substituted with he name of the mailing list. Note that the trailing "s" is required².

For example, a footer containing the following text:

This is the \%(list_name)s mailing list
Description: \%(description)s

might get attached to postings like so:

This is the Example mailing list
Description: An example of Mailman mailing lists

Here is the list of substitution variables available for your headers and footers:

real_name

This is the value of the real_name configuration variable in the General options category.

list_name

This is the canonical name of the mailing list. In other words it's the posting address of the list³.

host_name

This is the domain name part of the email address for this list.

web_page_url

This is the base url for contacting the list via the web. It can be appended with listinfo/%(list_name)s to yield the general list information page for the mailing list.

description

The brief description of the mailing list.

info

This is the full description of the mailing list.

cgiext

This is the extension added to CGI scripts. It might be the empty string, .cgi, or something else depending on how your site is configured.

Note that real_name, host_name, description, and info substitution variables take their values from the list configuration variables of the same name.

When personalization is enabled, the following substitution variables are also available:

user_address

The address of the recipient of the message, coerced to lower case.

user_delivered_to

The case-preserved address that the user subscribed to the mailing list with⁴.

user_password

The user's password, in clear text.

user_name

The user's full name.

user_optionsurl

The url to the user's personal options page.

To the top

Digest Options

Digest delivery is a way to bundle many articles together into one package, which can be delivered once per day (if there were any posted articles), or whenever the package is bigger than a specified limit. Some users may prefer this style of delivery for higher traffic lists since they will receive fewer messages.

Mailman supports two standard digest formats, and if digests are enabled, users can select which of the two formats they receive. One is MIME digests, where each message is an attachment inside a multipart/digest. This format also contains a summary table of contents, and of course the an optional header and footer, and it retains most of the headers of the original messages.

The second type is called ``plaintext'' digests because they are readable in mail readers that don't support MIME. Actually, they adhere to the RFC 1153 digest standard. The retain some, but not all of the original messages, but can also include a summary and headers and footers.

Like non-digest delivery, you can enable or disable digest delivery, but you cannot disable both types of delivery. You can specify different headers and footers for digest and non-digest deliveries. You cannot personalize digest deliveries.

As list administrator, you may want to send an urgent message to all list members, bypassing the normal digest bundling. To do this, send the message with a Urgent: header, where the value of the header is the list administrator's password. Non-digest members will receive the message like normal, but digest members will receive the message immediately⁵.

Here are the variables which control digest delivery:

digestable

The option controls whether members can receive digest deliveries or not. If not, they will be forced to receive immediate deliveries. You can't disable digests if non-digests are already disabled.

digest_is_default

Controls which style of delivery is the default for new members. You can choose Regular (non-digest) or Digest delivery.

mime_is_default_digest

If a member is allowed to choose digests, this variable controls which is the default digest style they will receive. Plain digests are RFC 1153 format as described above.

digest_size_threshold

Normally, digest members get at least one message per day, if there have been any messages posted to the list. However, for high volume lists, you may want to send out digests when the size has reached a certain threshold, otherwise, the one digest they receive could be huge. This variable controls the size threshold by specifying the maximum digest size in kilobytes. Note that this threshold isn't exact. Set this variable to zero to specify that there is no size threshold, in which case no more than one digest will be sent out per day.

digest_send_periodic

This variable actually controls whether or not a digest is sent daily when the size threshold has not yet been met. If set to No, then digests will only be sent when they are bigger than digest_size_threshold.

digest_header

This text box lets you enter information that will be included in the header of every digest message sent through the list. The same information can go in this header as can go in the msg_header, except for the personalization variables.

digest_footer

Just like with the header, you can add a footer to every message. The same rules apply to digest footers as apply to digest headers.

digest_volume_frequency

Each digest is numbered with a volume and an issue. This variable controls how often a new digest volume is sent. When the digest volume number is incremented, the issue number is reset to 1.

_new_volume

This is an action variable, which forces an increment of the volume number as soon as you submit the form.

_send_digest_now

This is another action variable. Select Yes, submit the form, and the current digest is packaged up and sent to digest members, regardless of size (well, there has to be at least one message in the digest).

To the top

Privacy Options

The Privacy category lets you control how much of the list's information is public, as well as who can send messages to your list. It also contains some spam detection filters. Note that this section is not used to control whether your list's archives are public or private; for that, use the category.

There are four sub-categories:

• Subscription rules - i.e. the rules for joining and leaving your mailing list
• Sender filters - the rules for who may post messages to your list
• Recipient filters - moderation rules based on the recipient of the message
• Spam filters - some regular expression based rules for header matching

The sender, recipient, and spam filtering rules are part of the general list moderation features of Mailman. When a message is posted to the list, it is matched against a number of criteria, the outcome of which determines whether the message is reflected to the membership or not. In general, the outcome is one of four states:

• Approved or Accepted - the message may be sent on to the members of the mailing list.
• Hold - the message will be held for moderator approval. The list owners and moderators will then have to explicitly approve the message before the list members will see it.
• Reject - the message is bounced back to the original sender, often with a notice containing the reason the message was rejected. The list members never see rejected messages.
• Discard - the message is simply thrown away without further processing.

Many of the fields in this section are text boxes accepting addresses, one per line. Unless otherwise noted, these also accept regular expressions which will be matched against an address, if the line begins with a (caret) character.

Bounce Processing

These policies control the automatic bounce processing system in Mailman. Here's an overview of how it works:

When a bounce is received, Mailman tries to extract two pieces of information from the message: the address of the member the message was intended for, and the severity of the problem causing the bounce. The severity can be either hard for fatal errors, or soft for transient errors. When in doubt, a hard severity is used.

If no member address can be extracted from the bounce, then the bounce message is usually discarded. Every member has a bounce score, initialized at zero, and every time we encounter a bounce from a member we increment that member's score. Hard bounces increment by 1 while soft bounces increment by 0.5. We only increment the bounce score once per day, so even if we receive ten hard bounces from a member per day, their score will increase by only 1 for that day.

When a member's bounce score is greater than the bounce score threshold (see below), the member's subscription is disabled. Once disabled, the member will not receive any postings from the list until their membership is explicitly re-enabled, either by the list administrator or the user. However, they will receive occasional reminders that their membership has been disabled, and these reminders will include information about how to re-enable their membership. You can control both the number of reminders the member will receive and the frequency with which these reminders are sent.

There is one other important configuration variable; after a certain period of time - during which no bounces from the member are received - the bounce information is considered stale and discarded. Thus by adjusting this value, and the score threshold, you can control how quickly bouncing members are disabled. You should tune both of these to the frequency and traffic volume of your list.

bounce_processing

Specifies whether or not this list should do automatic bounce processing.

bounce_score_threshold

This is the bounce score above which a member's subscription will be automatically disabled. When the subscription is re-enabled, their bounce score will be reset to zero. This value can be a floating point number.

bounce_info_stale_after

Thenumber of days after which a member's bounce information is considered stale. If no new bounces have been received in the interrim, the bounce score is reset to zero. This value must be an integer.

bounce_you_are_disabled_warnings

The number of notices a disabled member will receive before their address is removed from the mailing list's roster. Set this to 0 to immediately remove an address from the list once their bounce score exceeds the threshold. This value must be an integer.

bounce_you_are_disabled_warnings_interval

The number of days between each disabled notification.

bounce_unrecognized_goes_to_list_owner

This variable controls whether unrecognized bounces are discarded, or forwarded on the list administrator. The bounce detector isn't perfect, although personalization can make it much more accurate. The list owner may want to receive unrecognized bounces so that they can manually disable or remove such members.

bounce_notify_owner_on_disable

This option controls whether or not the list owner is notified when a member's subscription is automatically disabled due to their bounce threshold being reached.

bounce_notify_owner_on_removal

This option controls whether or not the list owner is notified when a member is removed from the list after their disabled notifications have been exhausted.

Archiving Options

Mailman comes with a built-in web-based archiver called Pipermail, although it can be configured to use external, third party archivers.

archive

This option tells Mailman whether to archive messages it receives or not, regardless of whether Pipermail or a third party archiver is used. Turn this off if you don't want to archive messages.

Note that senders can control whether their own posts are archived, on an individual per-message basis. If the posted message has a X-No-Archive: header (regardless of value), or a X-Archive: header with a value of No (case insensitive), then the message will not be archived, although it will be treated as normal in all other ways.

archive_private

Controls whether Pipermail archives are private or public. Private archives require a valid member address and password, or a list administrator password in order to access them. This option has no effect when a third party archiver is used.

archive_volume_frequency

Controls how Pipermail splits messages in the archive. The most common option is Monthly meaning a new archive volume is started every month. Very high volume lists may want a shorter frequency (e.g. Weekly or Daily) where as lower volume lists may want a longer frequency (e.g. Yearly). This option has no effect when a third party archiver is used.

To the top

Mail/News Gateway

Mailman has a sophisticated mail-to-news gateway feature. It can independently gate messages from news to mail and vice versa, and can even be used to manage moderated newsgroups.