path: root/doc/mailman-admin.tex

\documentclass{howto}

\title{GNU Mailman - List Administration Manual}

% Increment the release number whenever significant changes are made.
% The author and/or editor can define 'significant' however they like.
\release{1.0}

% At minimum, give your name and an email address.  You can include a
% snail-mail address if you like.
\author{Barry A. Warsaw}
%\authoraddress{barry (at) list dot org}

\date{\today}			% XXX update before tagging release!
\release{2.1}			% software release, not documentation
\setreleaseinfo{}		% empty for final release
\setshortversion{2.1}		% major.minor only for software

\begin{document}
\maketitle

% This makes the Abstract go on a separate page in the HTML version;
% if a copyright notice is used, it should go immediately after this.
%
\ifhtml
\chapter*{Front Matter\label{front}}
\fi

% Copyright statement should go here, if needed.
% ...

% The abstract should be a paragraph or two long, and describe the
% scope of the document.
\begin{abstract}
\noindent
This document describes the list administrator's interface for GNU
Mailman 2.1.  It contains information a list owner would need to
configure their list, either through the web interface or through
email.  It also covers the moderator's interface for approving held
messages and subscription notices, and the web interface for creating
new mailing lists.  In general, it does not cover the command line
interface to Mailman, installing Mailman, or interacting with Mailman
from the point of view of the user.  That information is covered in
other manuals.
\end{abstract}

\tableofcontents

\section{Introduction to GNU Mailman}

GNU Mailman is software that lets you manage electronic mailing lists.
It supports a wide range of mailing list types, such as general
discussion lists and announce-only lists.  Mailman has extensive
features for controlling the privacy of your lists, distributing your
list as personalized postings or digests, gatewaying postings to and
from Usenet, and providing automatic bounce detection.  Mailman
provides a built-in archiver, multiple natural languages, as well as
advanced content and topic filtering.

Mailman provides several interfaces to its functionality.  Most list
administrators will primarily use the web interface to customize their
lists.  There is also a limited email command interface to the
administrative functions, as well as a command line interface if you
have shell access on the Mailman server.  This document does not cover
the command line interface; see the GNU Mailman site administrator's
manual for more details.

\subsection{A List's Email Addresses}

Every mailing list has a set of email addresses that messages can be
sent to.  There's always one address for posting messages to the list,
one address that bounces will be sent to, and addresses for processing
email commands.  For example, for a mailing list called
\var{mylist@example.com}, you'd find these addresses:

\begin{itemize}
\item mylist@example.com -- this is the email address people should
      use for new postings to the list.

\item mylist-join@example.com -- by sending a message to this address,
      a new member can request subscription to the list.  Both the
      \mailheader{Subject} header and body of such a message are
      ignored.  Note that mylist-subscribe@example.com is an alias for
      the -join address.

\item mylist-leave@example.com -- by sending a message to this address,
      a member can request unsubscription from the list.  As with the
      -join address, the \mailheader{Subject} header and body of the
      message is ignored.  Note that mylist-unsubscribe@example.com is
      an alias for the -leave address.

\item mylist-owner@example.com -- This address reaches the list owner
      and list moderators directly.

\item mylist-request@example.com -- This address reaches a mail robot
      which processes email commands that can be used to set member
      subscription options, as well as process other commands.

\item mylist-bounces@example.com -- This address receives bounces from
      members who's addresses have become either temporarily or
      permanently inactive.  The -bounces address is also a mail robot
      that processes bounces and automatically disables or removes
      members as configured in the bounce processing settings.  Any
      bounce messages that are either unrecognized, or do not seem to
      contain member addresses, are forwarded to the list
      administrators.

\item mylist-confirm@example.com -- This address is another email
      robot, which processes confirmation messages for subscription
      and unsubscription requests.
\end{itemize}

There's also an -admin address which also reaches the list
administrators, but this address only exists for compatibility with
older versions of Mailman.

\subsection{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 interchangably, meaning both roles.  When
necessary, we'll distinguish the list moderator explicitly.

\subsection{A List's 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 \var{mylist} hosted at the domain
\var{lists.example.com}, you would typically access the administrative
pages by going to \code{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
\code{http://lists.example.com/mailman/admindb/mylist} (note the
\emph{admindb} url as opposed to the \emph{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.

\subsection{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 \emph{queues} depending on the address the
message was sent to.  For example, if your system has a mailing list
named \var{mylist} and your domain is \var{example.com}, people can
post messages to your list by sending them to
\var{mylist@example.com}.  These messages will be dropped into the
\emph{incoming} queue, which is also colloquially called the
\emph{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 \emph{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
\file{.db} and the message file has a suffix of either \file{.msg} if
stored in plain text, or \file{.pck} if stored in a more efficient
internal representation\footnote{Specifically, a Python pickle}.

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.

\section{The List 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.

\subsection{The General Options Category}

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.

\subsubsection{General list personality}

These variables, grouped under the general list personality section,
control some public information about the mailing list.

\begin{description}
\item[real_name]
    Every mailing list has both a \emph{posting name} and a \emph{real
    name}.  The posting name shows up in urls and in email addresses,
    e.g. the \code{mylist} in \code{mylist@example.com}.  The posting
    name is always presented in lower case, with alphanumeric
    characters and no spaces.  The list's real name is used in some
    public information and email responses, such as in the general
    list overview.  The real name can differ from the posting name by
    case only.  For example, if the posting name is \code{mylist}, the
    real name can be \code{Posting}.

\item[owner]
    This variable contains a list of email addresses, one address per
    line, of the list owners.  These addresses are used whenever the
    list owners need to be contacted, either by the system or by end
    users.  Often, these addresses are used in combination with the
    \code{moderator} addresses (see below).

\item[moderator]
    This variable contains a list of email addresses, one address per
    line, of the list moderators.  These addresses are often used in
    combination with the \code{owner} addresses.  For example, when
    you email \code{mylist-owner@example.com}, both the owner and
    moderator addresses will receive a copy of the message.

\item[description]
    In the general list overview page, which shows you every available
    mailing list, each list is displayed with a short description.
    The contents of this variable is that description.  Note that in
    emails from the mailing list, this description is also used in the
    comment section of the \mailheader{To} address.  This text should
    be relatively short and no longer than one line.

\item[info]
    This variable contains a longer description of the mailing list.
    It is included at the top of the list's information page, and it
    can contain HTML.  However, blank lines will be automatically
    converted into paragraph breaks.  Preview your HTML though,
    because unclosed or invalid HTML can prevent display of parts of
    the list information page.

\item[subject_prefix]
    This is a string that will be prepended to the
    \mailheader{Subject} header of any message posted to the list.
    For example, if a message is posted to the list with a
    \mailheader{Subject} like:

    \begin{verbatim}
    Subject: This is a message
    \end{verbatim}

    and the \code{subject_prefix} is \code{[My List] } (note the
    trailing space!), then the message will be received like so:

    \begin{verbatim}
    Subject: [My List] This is a message
    \end{verbatim}

    If you leave \code{subject_prefix} empty, no prefix will be added
    to the \mailheader{Subject}.  Mailman is careful not to add a
    prefix when the header already has one, as is the case in replies
    for example.  The prefix can also contain characters in the list's
    preferred language.  In this case, because of vagarities of the
    email standards, you may or may not want to add a trailing space.

\item[anonymous_list]
    This variable allows you to turn on some simple anonymizing
    features of Mailman.  When you set this option to \emph{Yes},
    Mailman will remove or replace the \mailheader{From},
    \mailheader{Sender}, and \mailheader{Reply-To} fields of any
    message posted to the list.

    Note that this option is simply an aid for anonymization, it
    doesn't guarantee it.  For example, a poster's identity could be
    evident in their signature, or in other mail headers, or even in
    the style of the content of the message.  There's little Mailman
    can do about this kind of identity leakage.
\end{description}

\subsubsection{Reply-To header munging}

This section controls what happens to the \mailheader{Reply-To}
headers of messages posted through your list.

Beware!  \mailheader{Reply-To} munging is considered a religious issue
and the policies you set here can ignite some of the most heated
off-topic flame wars on your mailing lists.  We'll try to stay as
agnostic as possible, but our biases may still peak through.

\mailheader{Reply-To} is a header that is commonly used to redirect
replies to messages.  Exactly what happens when your uses reply to
such a message depends on the mail readers your users use, and what
functions they provide.  Usually, there is both a ``reply to sender''
button and a ``reply to all'' button.  If people use these buttons
correctly, you will probably never need to munge
\mailheader{Reply-To}, so the default values should be fine.

Since an informed decision is always best, here are links to two
articles that discuss the opposing viewpoints in great detail:

\begin{itemize}

\item \ulink{Reply-To Munging Considered
      Harmful}{http://www.unicom.com/pw/reply-to-harmful.html}
\item \ulink{Reply-To Munging Considered
      Useful}{http://www.metasystema.org/essays/reply-to-useful.mhtml}

\end{itemize}

The three options in this section work together to provide enough
flexibility to do whatever \mailheader{Reply-To} munging you might
(misguidingly :) feel you need to do.

\begin{description}

\item[first_strip_reply_to]
    This variable controls whether any \mailheader{Reply-To} header
    already present in the posted message should get removed before
    any other munging occurs.  Stripping this header will be done
    regardless of whether or not Mailman will add its own
    \mailheader{Reply-To} header to the message.

    If this option is set to \emph{No}, then any existing
    \mailheader{Reply-To} header will be retained in the posted
    message.  If Mailman adds its own header, it will contain
    addresses which are the union of the original header and the
    Mailman added addresses.  The mail standards specify that a
    message may only have one \mailheader{Reply-To} header, but that
    that header may contain multiple addresses.

\item[reply_goes_to_list]
    This variable controls whether Mailman will add its own
    \mailheader{Reply-To} header, and if so, what the value of that
    header will be (not counting original header stripping -- see
    above).

    When you set this variable to \emph{Poster}, no additional
    \mailheader{Reply-To} header will be added by Mailman.  This
    setting is strongly recommended.

    When you set this variable to \emph{This list}, a
    \mailheader{Reply-To} header pointing back to your list's posting
    address will be added.

    When you set this variable to \emph{Explicit address}, the value
    of the variable \code{reply_to_address} (see below) will be
    added.  Note that this is one situation where
    \mailheader{Reply-To} munging may have a legitimate purpose.  Say
    you have two lists at your site, an announce list and a discussion
    list.  The announce list might allow postings only from a small
    number of approved users; the general list membership probably
    can't post to this list.  But you want to allow comments on
    announcements to be posted to the general discussion list by any
    list member.  In this case, you can set the \mailheader{Reply-To}
    header for the announce list to point to the discussion list's
    posting address.

\item[reply_to_address]
    This is the address that will be added in the
    \mailheader{Reply-To} header if \code{reply_goes_to_list} is set
    to \emph{Explicit address}.

\end{description}

\subsubsection{Umbrella list settings}

TBD.  Note that umbrella lists are deprecated and will be replace with
a better mechanism for Mailman 3.0.

\subsubsection{Notifications}

Mailman sends notifications to the list administrators or list members
under a number of different circumstances.  Most of these
notifications can be configured in this section, but see the Bounce
Processing and Auto-responder categories for other notifications that
Mailman can send.

\begin{description}
\item[send_reminders]
    By default Mailman sends all list members a monthly password
    reminder.  This notice serves two purposes.  First, it reminds
    people about all the lists they may be subscribed to on this
    domain, including the lists where their subscription may be
    disabled.  Second, it reminds people about their passwords for
    these lists, as well as the url for their personal options pages,
    so that they can more easily configure their subscription options.

    Some people get annoyed with these monthly reminders, and they can
    disable the reminders via their subscription options page.  For
    some lists, the monthly reminders aren't appropriate for any of
    the members, so you can disable them list-wide by setting the
    \code{send_reminders} variable to \emph{No}.

\item[welcome_msg]
    When new members are subscribed to the list, either by their own
    action, or the action of a list administrator, a welcome message
    can be sent to them.  The welcome message contains some common
    boilerplate information, such as the name of the list,
    instructions for posting to the list, and the member's
    subscription password.  You can add additional information to the
    welcome message by typing the text into the \code{welcome_msg}
    text box.  Note that because this text is sent as part of an
    email, it should \strong{not} contain HTML.

\item[send_welcome_msg]
    This flag controls whether or not the welcome message is sent to
    new subscribers.

\item[goodbye_msg]
    Like the \code{welcome_msg}, a ``goodbye'' message can be sent to
    members when they unsubscribe from the list.  Unlike the welcome
    message, there's no boilerplate for the goodbye message.  Enter
    the entire goodbye message you'd like unsubscribing members to
    receive into the \code{goodbye_msg} text box.

\item[send_goodbye_msg]
    This flag controls whether or not the goodbye message is sent to
    unsubscribing members.

\item[admin_immed_notify]
    List moderators get notifications of pending administrative
    actions, such as subscription or unsubscription requests that
    require moderator approval, or posted messages that are being held
    for moderator approval.  List moderators will always get a daily
    summary of such pending requests, but they can also get immediate
    notifications when such a request is made.  The
    \code{admin_immed_notify} variable controls whether these
    immediate notifications are sent or not.  It's generally a good
    idea to leave this set to \emph{Yes}.

\item[admin_notify_mchanges]
    This variable controls whether the list administrators should get
    notifications when members join or leave the list.

\item[respond_to_post_requests]
    This variable controls whether the original sender of a posting
    gets a notice when their message is held for moderator approval.

\end{description}

\subsubsection{Additional settings}

This section contains some miscellaneous settings for your mailing
list.

\begin{description}
\item[emergency]
    When this option is enabled, all list traffic is emergency
    moderated, i.e. held for moderation.  Turn this option on when
    your list is experiencing a flamewar and you want a cooling off
    period.

\item[new_member_options]
    Each member has a set of subscription options which they can use
    to control how they receive messages and otherwise interact with
    the list.  While the members can change these settings by logging
    into their personal options page, you might want to set the
    default for a number of the member options.  You can do that with
    this variable, but see also the other categories for other member
    defaults you can set.

    This variable presents a set of checkboxes which control the
    defaults for some of the member options.  \emph{Conceal the
    member's address} specifies whether or not the address is
    displayed in the list roster.  \emph{Acknowledge the member's
    posting} controls whether or not Mailman sends an acknowledgement
    to a member when they post a message to the list.  \emph{Do not
    send a copy of a member's own post} specifies whether a member
    posting to the list will get a copy of their own posting.
    \emph{Filter out duplicate messages to list members (if possible)}
    specifies whether members who are explicitly listed as a recipient
    of a message (e.g. via the \mailheader{Cc} header) will also get a
    copy from Mailman.

    Of course, members can always override these defaults by making
    changes on their membership options page.

\item[administrivia]
    This option specifies whether Mailman will search posted messages
    for \emph{admimistrivia}, in other words, email commands which
    usually should be posted to the \code{-request} address for the
    list.  Setting this to \emph{Yes} helps prevent such things as
    unsubscribe messages getting erroneously posted to the list.

    If a message seems to contain administrivia, it is held for
    moderator approval.

\item[max_message_size]
    This option specifies a maximum message size, in kilobytes, over
    which the message will be held for moderator approval.

\item[host_name]
    This option specifies the host name part of email addresses used
    by this list.  For example, this is the \code{example.com} part of
    the posting address \code{mylist@example.com}.

    It's generally not a good idea to change this value, since its
    default value is specified when the mailing list is created.
    Changing this to an incorrect value could make it difficult to
    contact your mailing list.  Also not that the url used to visit
    the list's pages is not configurable through the web interface.
    This is because if you messed it up, you'd have to have the site
    administrator fix it.

\item[include_rfc2369_headers]
    \rfc{2369} is an internet standard that describes a bunch of
    headers that mailing list managers should add to messages to make
    it easier for people to interact with the list.  Mail reading
    programs which support this standard may provide buttons for easy
    access to the list's archives, or for subscribing and
    unsubscribing to the list.  It's generally a good idea to enable
    these headers as it provides for an improved user experience.
    These headers are often called the \code{List-*} headers.

    However, not all mail readers are standards compliant yet, and if
    you have a large number of members who are using non-compliant
    mail readers, they may be annoyed at these headers.  You should
    first try to educate your members as to why these headers exist,
    and how to hide them in their mail clients.  As a last resort you
    can disable these headers, but this is not recommended.

\item[include_list_post_header]
    The \mailheader{List-Post} header is one of the headers
    recommended by \rfc{2369}.  However for some announce-only mailing
    lists, only a very select group of people are allowed to post to
    the list; the general membership is usually not allowed to post to
    such lists.  For lists of this nature, the \mailheader{List-Post}
    header is misleading.  Select \emph{No} to disable the inclusion
    of this header. (This does not affect the inclusion of the other
    \code{List-*} headers.)
\end{description}

\subsection{The Passwords Category}
As mentioned above, there are two primary administrative roles for
mailing lists.  In this category you can specify the password for
these roles.

The list owner has total control over the configuration of their
mailing list (within some bounds as specified by the site
administrator).  Note that on this page, for historical reasons, the
list owner role is described here as the \emph{list administrator}.
You can set the list owner's password by entering it in the password
field on the left.  You must type it twice for confirmation.  Note
that if you forget this password, the only way for you to get back
into your list's administrative pages is to ask the site administrator
to reset it for you (there's no password reminders for list owners).

If you want to delegate list moderation to someone else, you can enter
a different moderator password in the field on the right (typed twice
for confirmation).  Note that if you aren't going to delegate
moderation, and the same people are going to both configure the list
and moderate postings to the list, don't enter anything into the
moderator password fields.  If you do enter a separate moderator
password, be sure to fill in the \code{moderator} variable in the
\emph{General options} category page. 

\subsection{The Language Options Category}
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 \emph{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 \emph{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:

\begin{description}
\item[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 \code{available_languages} variable.

\item[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 \code{preferred_language} variable.

\item[encode_ascii_prefixes]
    If your mailing list's preferred language uses a non-ASCII
    character set and the \code{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 \emph{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 \emph{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.
\end{description}

\subsection{The Membership Management Category}

The \emph{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.

\subsection{The Non-digest Options Category}

Mailman delivers messages to users via two modes.  List members can
elect to receive postings in bundles call \emph{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 \emph{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 \emph{personalized} which means
certain parts of the message can contain information tailored to the
member receiving the message.  For example, the \mailheader{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:

\begin{description}
\item[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.

\item[personalize]
    This option turns on message personalization.

\item[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.

\item[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.
\end{description}

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 \emph{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 \code{\%(list_name)s} is substituted with he name of
the mailing list.  Note that the trailing \samp{s} is
required\footnote{The site administrator can configure lists to use a
simpler interpolation format, where \code{\$list_name} or
\code{\$\{list_name\}} would be substituted with the mailing list's
name.  Ask your site administrator if the've configured your list this
way.}.

For example, a footer containing the following text:

\begin{verbatim}
This is the \%(list_name)s mailing list
Description: \%(description)s
\end{verbatim}

might get attached to postings like so:

\begin{verbatim}
This is the Example mailing list
Description: An example of Mailman mailing lists
\end{verbatim}

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

\begin{description}
\item[real_name]
    This is the value of the \code{real_name} configuration variable
    in the General options category.

\item[list_name]
    This is the canonical name of the mailing list.  In other words
    it's the posting address of the list\footnote{For backward
    compatibility, the variable \code{_internal_name} is
    equivalent.}.

\item[host_name]
    This is the domain name part of the email address for this list.

\item[web_page_url]
    This is the base url for contacting the list via the web.  It can
    be appended with \code{listinfo/\%(list_name)s} to yield the
    general list information page for the mailing list.

\item[description]
    The brief description of the mailing list.

\item[info]
    This is the full description of the mailing list.

\item[cgiext]
    This is the extension added to CGI scripts.  It might be the empty
    string, \code{.cgi}, or something else depending on how your site
    is configured.
\end{description}

Note that \code{real_name}, \code{host_name}, \code{description}, and
\code{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:

\begin{description}
\item[user_address]
    The address of the recipient of the message, coerced to lower case.

\item[user_delivered_to]
    The case-preserved address that the user subscribed to the mailing
    list with\footnote{Usually it makes no difference which of
    \code{user_address} and \code{user_delivered_to} is used, but it's
    important to remember that they can be different.  When they're
    different, Mailman always uses the lower case address as the key
    to the member's subscription information, but it always delivers
    messages to the case-preserved version.}.

\item[user_password]
    The user's password, in clear text.

\item[user_name]
    The user's full name.

\item[user_optionsurl]
    The url to the user's personal options page.
\end{description}

\subsection{The Digest Options Category}

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
\mimetype{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 \mailheader{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\footnote{They'll also receive the message in the
digest.}.

Here are the variables which control digest delivery:

\begin{description}
\item[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.

\item[digest_is_default]
    Controls which style of delivery is the default for new members.
    You can choose \emph{Regular} (non-digest) or \emph{Digest}
    delivery.

\item[mime_is_default_digest]
    If a member is allowed to choose digests, this variable controls
    which is the default digest style they will receive.  \emph{Plain}
    digests are \rfc{1153} format as described above.

\item[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.

\item[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
    \emph{No}, then digests will only be sent when they are bigger
    than \code{digest_size_threshold}.

\item[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
    \code{msg_header}, except for the personalization variables.

\item[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.
    
\item[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.

\item[_new_volume]
    This is an action variable, which forces an increment of the
    volume number as soon as you submit the form.

\item[_send_digest_now]
    This is another action variable.  Select \emph{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).
\end{description}

\subsection{The Privacy Options Category}

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 \ref{Archiving options} category.

There are four sub-categories:
\begin{itemize}
\item Subscription rules -- i.e. the rules for joining and leaving
      your mailing list

\item Sender filters -- the rules for who may post messages to your
      list

\item Recipient filters -- moderation rules based on the recipient of
      the message

\item Spam filters -- some regular expression based rules for header
      matching
\end{itemize}

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:

\begin{itemize}
\item Approved or Accepted -- the message may be sent on to the
      members of the mailing list.

\item 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.

\item 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.

\item Discard -- the message is simply thrown away without further
      processing.
\end{itemize}

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.

\subsubsection{Subscription rules}

This subcategory controls the rules for exposing the existance of this
list, and for what new members must do in order to subscribe to the
list.

\begin{description}
\item[advertised]
    This option controls whether this list will show up in the list
    overview for the site.  Normally, an overview contains the name
    and short description of every mailing list in the virtual
    domain.  By setting this variable to \emph{No}, it will not show
    up in this overview, nor will it show up in the administrative
    overview.  The only way then to find the list is to guess (or
    know!) its name.

\item[subscribe_policy]
    This option controls the steps that a new member must take to join
    the list.  The available options may differ based on some defaults
    that the site administrator chooses.  They are:

    \begin{itemize}
    \item None -- No verification is done on the subscribing
          member. This is also called \emph{open subscriptions} and is
          generally disabled by default.  The site administrator must
          allow list admins to choose this option; if not, this option
          will not be presented to you.

    \item Confirm -- An email confirmation step is required before the
          address is added to the list.  When a member requests
          subscription, either via the web page or by sending a
          message to \var{yourlist}\code{-join@example.com}, Mailman
          will send a confirmation message to the requesting address.
          This mail-back confirmation contains a unique identifier,
          which the requester can present to Mailman in order to
          confirm their subscription.  This can be done either by
          replying to the mail-back, or by visiting the url in the
          mail-back message.  The url points to a page that lets the
          user either discard or confirm their request.

    \item Require approval -- All subscription requests are held for
          approval of the list moderator.  No mail-back confirmation
          is sent, but the list admins will recieve a message
          indicating that approval is pending.

    \item Confirm and approve -- Here, a mail-back notice must first
          be confirmed by the requester.  Once confirmed, the list
          moderator must then approve the request.  This is the most
          secure method for users to subscribe since it both verifies
          the requesting address, and forces the list moderators to
          approve the request.

    \end{itemize}

\item[unsubscribe_policy]
    Specifies whether the list moderator's approval is required for
    unsubscription requests.  \emph{No} is highly recommended, since
    it is exceedingly impolite to not allow people to leave a mailing
    list whenever they want (i.e. opt-out).  \emph{Yes} is useful in
    some specialized contexts; e.g. you may not want to allow
    employees to unsubscribe from the company newsletter.

\item[ban_list]
    This contains a list of addresses (or regular expressiosn), one
    per line, that are banned from ever subscribing to your mailing
    list.  If a match occurs during the subscription process, the
    request will be automatically rejected, and the requester will get
    a rejection notice.  You can use this to permanently ban
    troublesome posters to a members-only list.

\item[private_roster]
    This specifies who is allowed to view the roster of member
    addresses.  If you choose \emph{Anyone}, then the list membership
    is completely public.  You can limit exposure of the roster to
    just list members, or just to the list administrators.  In the
    former case, a user must enter a valid member's address and
    password before they can view the roster.  In the latter case, a
    list administrator's password must be enter; if a matching admin
    password is entered, address field is ignored.

\item[obscure_addresses]
    Controls whether some simple obfuscation of addresses is used when
    member addresses are included on web pages.  This should reduce
    the opportunity for email address harvesting by spammers, although
    it probably doesn't eliminate it.
\end{description}

\subsubsection{Sender filters}

When a message is posted to the list, a series of moderation criteria are
applied to determine the disposition of the message.  This section
contains the modeation controls for postings from both members and
non-members.

\begin{description}
\item[default_member_moderation]
    Member postings are held for moderation if their \emph{moderation
    flag} is turned on.  Note that only the list administrators can
    change the value of a member's moderation flag.

    You can control whether new members get their moderation flag
    turned on or off by default when they subscribe to the list.  By
    turning this flag off by default, postings by members will be
    allowed without further intervention (barring other restrictions
    such as size or implicit recipient lists -- see below).  By
    turning the flag on, you can quarantine new member postings to
    make sure that they meet your criteria for netiquette, topicality,
    etc.  Once you determine that the new member understands the
    community's posting rules, you can turn off their moderation flag
    and let their postings go through unstopped.

    E-newsletter style lists can also be set up by using the
    moderation flag.  By setting the \code{member_moderation_action}
    to \emph{Reject}, and by turning off the moderation flag for just
    the few approved senders, your list will operate in essentially a
    one-way direction.  Note that you'd also need to reject or discard
    postings from non-members.

\item[member_moderation_action]
    This is the action to take for postings from a member who's
    moderation flag is set.  For typical discussion lists, you'll
    likely set this to \emph{Hold} so that the list moderator will get
    a chance to manually approve, reject, or discard the message.  For
    e-newsletter and announcement lists, you might want to set this to
    \emph{Reject} or \emph{Discard}.

    Note that when a moderated member posts to your list, and the
    \code{member_moderation_action} is set to \emph{Hold}, the message
    will appear on the administrative requests page.  When you dispose
    of the message, you will be given an opportunity to clear the
    moderation flag at the same time.   If you're quarantining new
    posts, this makes it very convenient to both approve a new
    member's post and de-moderate them at the same time.

\item[member_moderation_notice]
    When a member's moderation flag is turned on and
    \code{member_moderation_action} is \emph{Reject}, this variable
    contains the text sent in the rejection notice.
\end{description}

The next batch of variables controls what happens when non-members
post messages to the list.  Each of these accepts one email address
per line; regular expressions are allowed if the line starts with the
\^ (caret) character.  These address lists are always consulted in the
order in which they're presented on this page (i.e. accepts first,
followed by holds, rejections, and discards).

\begin{description}
\item[accept_these_nonmembers]
    Postings from non-members whose addresses match this list are
    accepted, barring other list restrictions due to size, implicit
    recipients, etc.  You might want to add alternative addresses of
    approved posters to this list.

\item[hold_these_nonmembers]
    Postings from non-members whose addresses match this list are
    held for moderator approval.

\item[reject_these_nonmembers]
    Postings from non-members whose addresses match this list are
    rejected, i.e. bounced back to the original sender.  There
    currently is no way to add additional text to the rejection
    message.

\item[discard_these_nonmembers]
    Postings from non-members whose addresses match this list are
    discarded, with no bounce back message.  You might want to add the
    addresses of known spammers to this list.

\item[generic_nonmember_action]
    This variable controls what happens to non-member posts when the
    address of the sender doesn't match any of the above four lists.
    If you set this to \emph{Hold}, the posting will appear on the
    administrative requests page, and you will be given an opportunity
    to add the non-member to one of the above four lists at the same
    time you dispose of the held message.

\item[forward_auto_discards]
    When messages from non-members are discarded, either because the
    sender address matched \code{discard_these_nonmembers}, or because
    \code{generic_nonmember_action} is \emph{Discard}, you can choose
    whether such messages are forwarded to the lsit administrators or
    not.
\end{description}

\subsubsection{Recipient Filters}

The variables in this section control various filters based on the
recipient of the message.

\begin{description}
\item[require_explicit_destination]
    This controls whether the mailing list posting address must be
    explicitly named in the \mailheader{To} or \mailheader{Cc}
    recipient lists.  The main reason why it wouldn't is if the
    message was blind-carbon-copied (i.e. \mailheader{Bcc}'d) to the
    list.  Spammers like to do this, but sometimes legitimate messages
    are forwarded to the list this way.

    If the list is not explicitly addressed and this setting is turned
    on, the message will be held for moderator approval.

\item[acceptable_aliases]
    This is the list of alternative addresses that are acceptable as a
    list posting address when \code{require_explicit_destination} is
    enabled.  This is useful for when there aliases for the main
    posting address (e.g. \code{help@example.com} may be an alias for
    \code{help-list@example.com}).

\item[max_num_recipients]
    This is the maximum number of explicit recipients that are allowed
    on the posted message.  Spammers sometimes send messages with lots
    of explicit recipients, so setting this number to a reasonable
    value may cut down on spam.
\end{description}

\subsubsection{Spam Filters}

This section provides some adjuncts to spam fighting tools; it
doesn't replace dedicated anti-spam tools such as SpamAssassin or
Spambayes.

\begin{description}
\item[bounce_matching_headers]
    This variable contains header regular expressions, one per line,
    and if any of a message's headers matches one of these patterns,
    it will be held for moderation.  The format is a colon separated
    header and value, where the header is case insensitive and the
    value is any valid Python regular expression.  Lines that start
    with \# are ignored.

    This variable can be used to catch known spammers by writing
    regexps that match against \mailheader{To} or \mailheader{Cc}
    lines, or known-bad \mailheader{Message-ID}s.  Perhaps more useful
    though are patterns that match headers added by spam detection
    tools higher up in the tool chain.  For example, you might
    configure SpamAssassin to add an \mailheader{X-Spam-Score} header
    with between zero and 5 stars depending on the spam score.  Then
    you can add a line to this variable like:

    \begin{verbatim}
    X-Spam-Score: [*]{3,5}
    \end{verbatim}

    This line will match from 3 to 5 stars in the value of this
    field.
\end{description}

\subsection{The Bounce Processing Category}

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 \emph{hard} for fatal errors, or
\emph{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 \emph{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 \emph{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.

\begin{description}

\item[bounce_processing]
    Specifies whether or not this list should do automatic bounce
    processing.

\item[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.

\item[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.

\item[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.

\item[bounce_you_are_disabled_warnings_interval]
    The number of days between each disabled notification.

\item[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.

\item[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.

\item[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.
\end{description}

\subsection{The Archiving Options Category}

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

\begin{description}

\item[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 \mailheader{X-No-Archive} header (regardless of
    value), or a \mailheader{X-Archive} header with a value of
    \code{No} (case insensitive), then the message will not be
    archived, although it will be treated as normal in all other
    ways.

\item[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.

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

\subsection{The Mail/News Gateway Category}

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.

\subsection{The Auto-responder Category}
\subsection{The Content Filtering Category}
\subsection{The Topics Category}

\section{Membership Management}
\section{Tending to Pending Moderator Requests}
\section{Editing the Public HTML Pages}
\section{Deleting the Mailing List}

\appendix

\section{This is an Appendix}

To create an appendix in a Python HOWTO document, use markup like
this:

\begin{verbatim}
\appendix

\section{This is an Appendix}

To create an appendix in a Python HOWTO document, ....


\section{This is another}

Just add another \section{}, but don't say \appendix again.
\end{verbatim}


\end{document}