#pragma page-filename DOC/versions/786544
{{{#!wiki

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.
}}}

{{{#!wiki warning

Under Construction


I (Terri) am currently in the process of importing the 2.1 documentation from latex. It's fairly likely that there will be syntax issues and missing pieces. Please bear with me, and feel free to fix markup if you see a flaw.
Older versions of this document can be found at the following locations:<<BR>>
[[http://terri.zone12.com/doc/mailman/mailman-admin/|Mailman list administration manual in HTML format]]<<BR>> [[http://terri.zone12.com/doc/mailman/mailman-admin.pdf|Mailman list administration manual in PDF format]]<<BR>>
Or the information is also available on list.org:<<BR>>
[[http://list.org/mailman-admin/|http://list.org/mailman-admin/]]<<BR>> [[http://list.org/mailman-admin.pdf|http://list.org/mailman-admin.pdf]]
}}}

<<TableOfContents>>

= Introduction =

This is one of a set of three documents for the various people involved in running and using a mailing list. For the members of mailing lists (the subscribers), we have the [[../Mailman 2.1 Members Manual|Mailman 2.1 Members Manual]] which covers things like subscribing and unsubscribing. For the people who install and set up Mailman, we will eventually have the [[../Mailman 2.1 Site Administration Manual|Mailman 2.1 Site Administration Manual]], which has not yet been written.

This document covers the people who run mailing lists: the list administrators (who can change all the list options, as well as authorize postings that have been held for moderation), and the list moderators (who cannot modify list settings).

This document does not need to be read in order, so if you just want an answer to a specific question, jump to the appropriate place and references to other sections will be provided when necessary or potentially helpful.

== Acknowledgements ==

The bulk of this document has been written by Terri Oda. Terri used to get a lot of spam, so she did research into neat evolutionary anti-spam solutions. And then she thought it would be nice if her grandfather could use the web without worrying about bad stuff getting into his computer, so she started doing web security. All of this is a roundabout way of saying that her day job is as a security researcher, and she actually doesn't consider herself a document writer, but she was tired of Mailman not having documentation so she figured it was time to do something about it.

The original site admin docs were written by Barry Warsaw. Thanks also go to the rest of the Mailman team who provided the inline help upon which much of this documentation is based.

This document is now stored in the Mailman wiki [[http://wiki.list.org|http://wiki.list.org]], and may be edited and added to by members of the Mailman community. Please see the wiki changelogs for more information.

= Mailman's interfaces =

Mailman has 3 interfaces:

 * The web interface – used by most people, this is the main interface most users will see
 * The email interface – used as an alternative to the web interface
 * The command line interface – used mostly by site admins, this is very powerful but perhaps not so user-friendly

== The web interface ==

The most commonly used interface of Mailman is the web interface. Almost all the options can be set from this interface, and it also provides inline help and descriptions of each option. More importantly, the day-to-day tasks of running a mailing list are handed through this interface.

Assuming a fairly standard configuration, the configuration interface has a URL like this:

`http://WEBSERVER/mailman/admin/LISTNAME`

And the moderation interface has a very similar URL as follows:

`http://WEBSERVER/mailman/admindb/LISTNAME`

{{{#!wiki caution


The web domain (WEBSERVER) can't be set from the web, since it's a bit too easy to render your web interface unusable by making a typo. As such, this setting is usually changed from the command line. The '''fix_url''' script is provided for this purpose. It is used in conjuction with withlist as follows:<<BR>>
`bin/withlist -l -r fix_url listname [options]`
}}}

In many cases, this is the only interface a list administrator will use, and may be the only interface the list administrator has permissions to use.

== The email interface ==

There is also an email interface for Mailman, allowing list admins to adjust settings or handle caught messages without requiring them to open up a web browser.

{{{#!wiki caution


Since this interface is not as commonly used as the web interface, it is highly likely that this part of the documentation will be among the last pieces written. If you wish to speed this up, please feel free to help fill it in!
}}}

= Moderation =

The web interface for moderation can be found at a URL similar to the following, depending on your mailman config:

`http://WEBSERVER/mailman/admindb/LISTNAME`

From here, you will see a list of anything awaiting your decision. This is largely messages that have been caught for some reason, but may also include subscription/unsubscription requests if you require admin authorization before someone can join or leave the list.

== Why do I have to authorize these messages? ==

Messages are "caught" in the moderation queue depending upon your list settings. There are a number of rules that allow you to choose which messages require moderation, but basically you want things which might be inappropriate to be caught by these filters so a human can choose whether they get sent to all subscribers or not.

For example, as an anti-spam measure, many lists only accept messages from their members. Any non-member who sends a message will have it caught in the moderation queue. If the message turns out to be spam, it can be discarded, but if it turns out to be from someone posting from their work address, you may wish to send it out anyhow.  See the [[#Sender_filters|Sender filters]] section.

== How do I moderate messages? ==

For each message displayed in the queue, Mailman will give a summary of the message. This includes the following:

 * The sender's address
 * The subject of the message
 * The size
 * The reason the message was held for moderation (e.g.: "Post by non-member to a members-only list")
 * The date/time the message was received

A link is provided so you can read the entire message if you want to.

There are 4 choices when it comes to moderating a message:

 1. '''Defer'''<<BR>> This option allows you to put off the choice until later. It leaves the message in the queue and does nothing to it.
 1. '''Accept'''<<BR>> This accepts the message, allowing it to be sent to all of your subscribers.
 1. '''Reject'''<<BR>> This rejects the message, letting the sender know that it was rejected. You may also include a message explaining why. The reject option is usually used for messages which are inappropriate for that list for some reason – they may have attachments which are too large, be off-topic, or from someone who is not allowed to post to that list. Rejected messages are not sent to the list.
 1. '''Discard'''<<BR>> This discards the message, ensuring that it is not sent to the list. In this case, no message is sent to the sender. This option is most often used for spam messages.

In addition, there is a checkbox (near the submit button) which allows you to "Discard all messages marked Defer" – this allows you to bulk-discard spam messages and can be a very handy option. It only applies to the messages displayed in the queue page as you've loaded it.

== Why do I have to authorize subscriptions/unsubscriptions? ==

This is a setting chosen when the list was set up. If you do not wish to moderate subscription/unsubscription requests, you can change your list config.  See the `subscribe_policy` setting in the [[#Subscription_rules|Subscription rules]] section.

== How do I handle subscriptions/unsubscriptions ==

The interface for moderating members joining and leaving is similar to that for messages, only instead of a message summary we have the email address and name of the person under consideration.

The options for subscriptions and unsubscriptions are the same as those for messages:

 1. '''Defer'''<<BR>> Decide later.
 1. '''Accept'''<<BR>> Allow this person to subscribe or unsubscribe
 1. '''Reject'''<<BR>> Reject this person's request, letting them know and optionally giving them a reason for the rejection.
 1. '''Discard'''<<BR>> Discard this person's request silently, dropping it from the queue without notifying the person.

= Configuration =

== 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.

=== General List Personality ===

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

'''real_name'''
    Every mailing list has both a posting name and a real name. The posting name shows up in urls and in email addresses, e.g. the mylist in `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 mylist, the real name can be !MyList.

'''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 moderator addresses (see below).

'''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 owner addresses. For example, when you email `mylist-owner@example.com`, both the owner and moderator addresses will receive a copy of the message.

'''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 To: address. This text should be relatively short and no longer than one line.

'''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.

'''subject_prefix'''
    This is a string that will be prepended to the Subject: header of any message posted to the list. For example, if a message is posted to the list with a Subject: like:

        `Subject: This is a message`

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

        `Subject: [My List] This is a message`

    If you leave subject_prefix empty, no prefix will be added to the 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 the vagaries of the email standards, you may or may not want to add a trailing space.

'''from_is_list'''
    This applies to all non-digest messages sent by the list. For settings that apply only to messages whose From: domain publishes a DMARC p=reject or p=quarantine policy, see the dmarc_moderation_action description in the [[#Sender_filters|Sender filters]] section.<<BR>><<BR>>

    If set to Munge From, it replaces the From: header address with the list's posting address to mitigate issues stemming from the original From: domain's DMARC or similar policies and puts the original From: address in a Reply-To: header.<<BR>><<BR>>

    If set to Wrap Message it wraps the original message as a MIME subpart of an outer message with From: and Reply-To: headers as above.

'''anonymous_list'''
    This variable allows you to turn on some simple anonymizing features of Mailman. When you set this option to Yes, Mailman will remove or replace the From:, Sender:, and Reply-To: fields of any message posted to the list.<<BR>><<BR>>

    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.

=== Reply-To header munging ===

This section controls what happens to the `Reply-To:` headers of messages posted through your list.

Beware! `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.

`Reply-To:` is a header that is commonly used to redirect replies to messages. Exactly what happens when your users 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 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:

 * [[http://www.unicom.com/pw/reply-to-harmful.html|Reply-To Munging Considered Harmful]]
 * [[http://marc.merlins.org/netrants/reply-to-useful.html|Reply-To Munging Considered Useful]]

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

'''first_strip_reply_to'''
    This variable controls whether any `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 `Reply-To:` header to the message.

    If this option is set to ''No'', then any existing `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 Reply-To: header, but that that header may contain multiple addresses.

'''reply_goes_to_list'''
    This variable controls whether Mailman will add its own `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 ''Poster'', no additional `Reply-To:` header will be added by Mailman. This setting is strongly recommended.

    When you set this variable to ''This list'', a `Reply-To:` header pointing back to your list's posting address will be added.

    When you set this variable to ''Explicit address'', the value of the variable `reply_to_address` (see below) will be added. Note that this is one situation where `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 `Reply-To:` header for the announce list to point to the discussion list's posting address.

'''reply_to_address'''
    This is the address that will be added in the Reply-To: header if reply_goes_to_list is set to Explicit address.

=== Umbrella list settings ===

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

=== 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.

'''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.<<BR>><<BR>>

    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 `send_reminders` variable to ''No''.

'''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 ''welcome_msg'' text box. Note that because this text is sent as part of an email, it should '''not''' contain HTML.

'''send_welcome_msg'''
    This flag controls whether or not the welcome message is sent to new subscribers.

'''goodbye_msg'''
    Like the 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 `goodbye_msg` text box.

'''send_goodbye_msg'''
    This flag controls whether or not the goodbye message is sent to unsubscribing members.

'''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 `admin_immed_notify` variable controls whether these immediate notifications are sent or not. It's generally a good idea to leave this set to ''Yes''.

'''admin_notify_mchanges'''
    This variable controls whether the list administrators should get notifications when members join or leave the list.

'''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.

=== Additional settings ===

This section contains some miscellaneous settings for your mailing list.

'''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.

'''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.<<BR>><<BR>>

    This variable presents a set of checkboxes which control the defaults for some of the member options. Conceal the member's address specifies whether or not the address is displayed in the list roster. Acknowledge the member's posting controls whether or not Mailman sends an acknowledgement to a member when they post a message to the list. 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. 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 Cc: header) will also get a copy from Mailman.<<BR>><<BR>>

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

'''administrivia'''
    This option specifies whether Mailman will search posted messages for admimistrivia, in other words, email commands which usually should be posted to the -request address for the list. Setting this to Yes helps prevent such things as unsubscribe messages getting erroneously posted to the list.<<BR>><<BR>>

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

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

'''host_name'''
    This option specifies the host name part of email addresses used by this list. For example, this is the `example.com` part of the posting address `mylist@example.com`.<<BR>><<BR>>

    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 note 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.

'''include_rfc2369_headers'''
    [[http://www.faqs.org/rfcs/rfc2369.html|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 `List-*` headers.<<BR>><<BR>>

    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.

'''include_list_post_header'''
    The `List-Post:` header is one of the headers recommended by [[http://www.faqs.org/rfcs/rfc2369.html|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 `List-Post:` header is misleading. Select No to disable the inclusion of this header. (This does not affect the inclusion of the other `List-*` headers.)

== Passwords ==

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 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 moderator variable in the General options category page.

== 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 languages 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.<<BR>><<BR>>

    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.


== 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 your 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 called 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[1].

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 local part of the posting address of the list[2].

'''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[3].

'''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.


Footnotes

[1]... required
    The site administrator can configure lists to use a simpler interpolation format, where $list_name or ${list_name} would be substituted with the mailing list's name. Ask your site administrator if they've configured your list this way.
[2]... list
    For backward compatibility, the variable _internal_name is equivalent.
[3]... with
    Usually it makes no difference which of user_address and 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.

'''scrub_nondigest'''
    If set to Yes, all messages from this list will have any non-plain text parts removed from the message, stored aside and replaced by hyperlinks in the message. If set to No, this 'scrubbing' is only done for messages in plain format digests and list archives.

=== Sibling Lists ===

Sibling lists are other lists in the installation whose regular (non-digest) members can be excluded or included as recipients of posts to this list. The following three settings control this.

'''regular_exclude_lists'''
    Lists whose regular members are excluded from delivery of a post from this list if the other list is explicitly addressed in To: or Cc:.

'''regular_exclude_ignore'''
    If set to Yes, ignore any regular_exclude_lists of which the poster is not a member. This is used to avoid not sending to the members of the other list in case the post might not be accepted by that other list.

'''regular_include_lists'''
    Lists whose regular members are included in delivery of a post from this list if the other list is not explicitly addressed in To: or Cc:.

== 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 [[http://www.faqs.org/rfcs/rfc1153.html|RFC 1153]] digest standard. They 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[1].

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, but ensure that digest_send_periodic is Yes in this case or no digests will be sent.

'''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).

Footnotes

[1]... immediately
    They'll also receive the message in the digest.

== 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.

=== Subscription rules ===

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

'''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 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.

'''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:

 * None - No verification is done on the subscribing member. This is also called 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.

 * 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 `yourlist-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.

 * 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.
 * 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.

'''unsubscribe_policy'''
    Specifies whether the list moderator's approval is required for unsubscription requests. 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). Yes is useful in some specialized contexts; e.g. you may not want to allow employees to unsubscribe from the company newsletter.

'''ban_list'''
    This contains a list of addresses (or regular expressions), 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.

'''private_roster'''
    This specifies who is allowed to view the roster of member addresses. If you choose 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 entered; if a matching admin password is entered, address field is ignored.

'''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.

=== Sender filters ===

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

'''default_member_moderation'''
    Member postings are held for moderation if their moderation flag is turned on. Note that only the list administrators can change the value of a member's moderation flag.<<BR>><<BR>>

    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.<<BR>><<BR>>

    E-newsletter style lists can also be set up by using the moderation flag. By setting the member_moderation_action to 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.

'''member_moderation_action'''
    This is the action to take for postings from a member whose moderation flag is set. For typical discussion lists, you'll likely set this to 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 Reject or Discard.<<BR>><<BR>>

    Note that when a moderated member posts to your list, and the member_moderation_action is set to 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.

'''member_moderation_notice'''
    When a member's moderation flag is turned on and member_moderation_action is Reject, this variable contains the text sent in the rejection notice.

The next group of settings control messages whose From: domain publishes a DMARC p=reject or p=quarantine policy.

'''dmarc_moderation_action'''
    These actions, Accept, Munge From, Wrap Message, Reject and Discard apply only to messages whose From: domain publishes a DMARC p=reject or optionally (see the next setting) p=quarantine policy. If the message is From: such a domain and this action is other than Accept, this action applies to the message. Otherwise the `from_is_list` setting in the [[#General_List_Personality|General_List_Personality]] section applies. See the `from_is_list` setting in the [[#General_List_Personality|General_List_Personality]] section for a description of the Munge From and Wrap Message actions.
'''dmarc_quarantine_moderation_action'''
    If this is set to Yes, the above dmarc_moderation_action applies to messages with From: domain DMARC policy p=quarantine as well as p=reject.
'''dmarc_moderation_notice'''
    When dmarc_moderation_action applies and is Reject, this variable contains the text sent in the rejection notice. If empty, a generic notice mentioning DMARC is sent.

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).

'''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.

'''hold_these_nonmembers'''
    Postings from non-members whose addresses match this list are held for moderator approval.

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

'''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.

'''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 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.

'''forward_auto_discards'''
    When messages from non-members are discarded, either because the sender address matched discard_these_nonmembers, or because generic_nonmember_action is Discard, you can choose whether such messages are forwarded to the list administrators or not.

=== Recipient filters ===

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

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

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

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

'''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.

=== Spam filters ===

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

'''header_filter_rules'''
    This section allows specification of one or more rules, each of which contains one or more regular expressions to be matched against the headers of an incoming message and a selection of an action (one of '''Defer''','''Hold''', '''Reject''', '''Discard''' or '''Accept''') to be applied to a message whose headers match one of the rule's regular expressions.

'''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.<<BR>><<BR>>

    This variable can be used to catch known spammers by writing regexps that match against To: or Cc: lines, or known-bad 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 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:

       ```X-Spam-Score: [*]{3,5}```

    This line will match from 3 to 5 stars in the value of this field.

== 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'''
    The number of days after which a member's bounce information is considered stale. If no new bounces have been received in the interim, 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.<<BR>><<BR>>
    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.

== Mail<->News gateways ==

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.

== Auto-responder ==

== Content filtering ==

== Topics ==

== Edit the public HTML pages and text files ==

= Creating a mailing list =

You can create a mailing list using either the web interface or the command-line interface.

== Using the web interface ==

The mailing list creation page is accessed via `http://WEBSERVER/mailman/create`.

This page contains some instructions and a form for you to fill in the required details:

'''Name of list:''' The real name of the list.

'''Initial list owner address:''' The email address of the list administrator.

'''Auto-generate initial list password:''' Yes or No.

'''Initial list password/Confirm initial password:''' Enter your required password here if you entered No in the auto-generate field.

'''Should new members be quarantined:''' Choose Yes to hold postings by new members for moderation.

'''Supported languages:''' Check all that apply.

'''Send "list created" email to list owner:''' Yes or No.

'''List creator's (authentication) password:''' This is the site administrator's password or the list creator's password which should have been created when the site was installed.

Click on the "Create list" button, and then you can go to configure the site as per the instructions above.

== Using a command-line ==

Lists are created from the command line with '''newlist'''. This is one of the [[DOC/4.09 Summary of the mailman bin commands|mailman/bin commands]]. Give the command `bin/newlist --help` for full information.

= Deleting the Mailing List =

Also see [[DOC/4.31 How do I remove a list via the web or command line?|this article]].


Removing/deleting mailing lists is performed with the command line tool '''rmlist'''. rmlist has 2 modes of operating:

 1. Only remove the list from the admin interface. This retains archives on file system (that is, postings) but makes the list completely inaccessible to users, this removes:
  * The list itself from the web admin interface as well as for users of the list
  * List meta data:
   * Name, description, etc.
   * Policies in place (for example, list moderation settings)
   * List members
 1. Like #1 above but also removes the list archives

If list archives are retained (default behavior), the archive files are left on the file system. If the archives are `private`, the Mailman administrator can still access the archives through web interface by authenticating with the site password, but list users (and the list administrator) will not have access because their authentications no longer exist. If the archives are `public`, pipermail URLs can still be used to access the archives without authentication.

NOTE removing the list completely may require manual editing of the mail aliases file, that is, /etc/aliases depending on the MTA and its integration with Mailman or lack thereof.

Once a list has been removed, it may be re-added with the '''newlist''' command line tool, however all information about the list (for example, description and previous members) will be missing. However, `private` archives which were retained will then be available to current members via the web interface.

It is also possible to allow mailing list removal via the web `admin` interface if the option/variable `OWNERS_CAN_DELETE_THEIR_OWN_LISTS` is enabled in '''mm_cfg.py'''; by default this option is disabled.