OMGW00T: After over a decade, the MailList mixin class is gone! Well,

[mailman.git] / Mailman / docs / cook-headers.txt

Cooking headers
===============

Messages that flow through the global pipeline get their headers 'cooked',
which basically means that their headers go through several mostly unrelated
transformations.  Some headers get added, others get changed.  Some of these
changes depend on mailing list settings and others depend on how the message
is getting sent through the system.  We'll take things one-by-one.

    >>> from email import message_from_string
    >>> from Mailman.Message import Message
    >>> from Mailman.Handlers.CookHeaders import process
    >>> from Mailman.configuration import config
    >>> from Mailman.database import flush
    >>> mlist = config.db.list_manager.create('_xtest@example.com')
    >>> mlist.subject_prefix = u''
    >>> mlist.include_list_post_header = False
    >>> mlist.archive = True
    >>> # XXX This will almost certainly change once we've worked out the web
    >>> # space layout for mailing lists now.
    >>> mlist.web_page_url = 'http://lists.example.com/'
    >>> flush()


Saving the original sender
--------------------------

Because the original sender headers may get deleted or changed, CookHeaders
will place the sender in the message metadata for safe keeping.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... A message of great import.
    ... """, Message)
    >>> msgdata = {}
    >>> process(mlist, msg, msgdata)
    >>> msgdata['original_sender']
    'aperson@example.com'

But if there was no original sender, then the empty string will be saved.

    >>> msg = message_from_string("""\
    ... Subject: No original sender
    ...
    ... A message of great import.
    ... """, Message)
    >>> msgdata = {}
    >>> process(mlist, msg, msgdata)
    >>> msgdata['original_sender']
    ''


X-BeenThere header
------------------

The X-BeenThere header is what Mailman uses to recognize messages that have
already been processed by this mailing list.  It's one small measure against
mail loops.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... A message of great import.
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> msg['x-beenthere']
    '_xtest@example.com'

Mailman appends X-BeenThere headers, so if there already is one in the
original message, the posted message will contain two such headers.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ... X-BeenThere: another@example.com
    ...
    ... A message of great import.
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> sorted(msg.get_all('x-beenthere'))
    ['_xtest@example.com', 'another@example.com']


Mailman version header
----------------------

Mailman will also insert an X-Mailman-Version header...

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... A message of great import.
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> from Mailman.Version import VERSION
    >>> msg['x-mailman-version'] == VERSION
    True

...but only if one doesn't already exist.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ... X-Mailman-Version: 3000
    ...
    ... A message of great import.
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> from Mailman.Version import VERSION
    >>> msg['x-mailman-version']
    '3000'


Precedence header
-----------------

Mailman will insert a Precedence header, which is a de-facto standard for
telling automatic reply software (e.g. vacation(1)) not to respond to this
message.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... A message of great import.
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> from Mailman.Version import VERSION
    >>> msg['precedence']
    'list'

But Mailman will only add that header if the original message doesn't already
have one of them.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ... Precedence: junk
    ...
    ... A message of great import.
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> from Mailman.Version import VERSION
    >>> msg['precedence']
    'junk'


RFC 2919 and 2369 headers
-------------------------

This is a helper function for the following section.

    >>> def list_headers(msg):
    ...     print '---start---'
    ...     # Sort the List-* headers found in the message.  We need to do
    ...     # this because CookHeaders puts them in a dictionary which does
    ...     # not have a guaranteed sort order.
    ...     for header in sorted(msg.keys()):
    ...         parts = header.lower().split('-')
    ...         if 'list' not in parts:
    ...             continue
    ...         for value in msg.get_all(header):
    ...             print '%s: %s' % (header, value)
    ...     print '---end---'

These RFCs define headers for mailing list actions.  A mailing list should
generally add these headers, but not for messages that aren't crafted for a
specific list (e.g. password reminders in Mailman 2.x).

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, dict(_nolist=True))
    >>> list_headers(msg)
    ---start---
    ---end---

Some people don't like these headers because their mail readers aren't good
about hiding them.  A list owner can turn these headers off.

    >>> mlist.include_rfc2369_headers = False
    >>> flush()
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> list_headers(msg)
    ---start---
    ---end---

But normally, a list will include these headers.

    >>> mlist.include_rfc2369_headers = True
    >>> mlist.include_list_post_header = True
    >>> mlist.preferred_language = 'en'
    >>> flush()
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> list_headers(msg)
    ---start---
    List-Archive: <http://www.example.com/pipermail/_xtest@example.com>
    List-Help: <mailto:_xtest-request@example.com?subject=help>
    List-Id: <_xtest.example.com>
    List-Post: <mailto:_xtest@example.com>
    List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-join@example.com>
    List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-leave@example.com>
    ---end---

If the mailing list has a description, then it is included in the List-Id
header.

    >>> mlist.description = 'My test mailing list'
    >>> flush()
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> list_headers(msg)
    ---start---
    List-Archive: <http://www.example.com/pipermail/_xtest@example.com>
    List-Help: <mailto:_xtest-request@example.com?subject=help>
    List-Id: My test mailing list <_xtest.example.com>
    List-Post: <mailto:_xtest@example.com>
    List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-join@example.com>
    List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-leave@example.com>
    ---end---

Administrative messages crafted by Mailman will have a reduced set of headers.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, dict(reduced_list_headers=True))
    >>> list_headers(msg)
    ---start---
    List-Help: <mailto:_xtest-request@example.com?subject=help>
    List-Id: My test mailing list <_xtest.example.com>
    List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-join@example.com>
    List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-leave@example.com>
    X-List-Administrivia: yes
    ---end---

With the normal set of List-* headers, it's still possible to suppress the
List-Post header, which is reasonable for an announce only mailing list.

    >>> mlist.include_list_post_header = False
    >>> flush()
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> list_headers(msg)
    ---start---
    List-Archive: <http://www.example.com/pipermail/_xtest@example.com>
    List-Help: <mailto:_xtest-request@example.com?subject=help>
    List-Id: My test mailing list <_xtest.example.com>
    List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-join@example.com>
    List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-leave@example.com>
    ---end---

And if the list isn't being archived, it makes no sense to add the
List-Archive header either.

    >>> mlist.include_list_post_header = True
    >>> mlist.archive = False
    >>> flush()
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... """, Message)
    >>> process(mlist, msg, {})
    >>> list_headers(msg)
    ---start---
    List-Help: <mailto:_xtest-request@example.com?subject=help>
    List-Id: My test mailing list <_xtest.example.com>
    List-Post: <mailto:_xtest@example.com>
    List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-join@example.com>
    List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
        <mailto:_xtest-leave@example.com>
    ---end---