path: root/Mailman/docs/hold.txt

Holding messages
================

One of the most important functions of Mailman is to moderate messages by
holding some for approval before they will post to the mailing list.  Messages
are held when they meet any of a number of criteria.

    >>> import os
    >>> import errno
    >>> from Mailman.Handlers.Hold import process
    >>> from Mailman.queue import Switchboard
    >>> from Mailman.configuration import config
    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
    >>> mlist.preferred_language = u'en'
    >>> mlist.real_name = u'_XTest'
    >>> # XXX This will almost certainly change once we've worked out the web
    >>> # space layout for mailing lists now.
    >>> mlist.web_page_url = u'http://lists.example.com/'

Here's a helper function used when we don't care about what's in the virgin
queue or in the pending database.

    >>> switchboard = Switchboard(config.VIRGINQUEUE_DIR)
    >>> def clear():
    ...     for filebase in switchboard.files:
    ...         msg, msgdata = switchboard.dequeue(filebase)
    ...         switchboard.finish(filebase)
    ...     for holdfile in os.listdir(config.DATA_DIR):
    ...         if holdfile.startswith('heldmsg-'):
    ...             os.unlink(os.path.join(config.DATA_DIR, holdfile))
    ...     try:
    ...         os.unlink(os.path.join(config.DATA_DIR, 'pending.db'))
    ...     except OSError, e:
    ...         if e.errno <> errno.ENOENT:
    ...             raise


Short circuiting
----------------

If the message metadata indicates that the message is pre-approved, then the
handler returns immediately.

    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ...
    ... An important message.
    ... """)
    >>> msgdata = {'approved': True}
    >>> process(mlist, msg, msgdata)
    >>> print msg.as_string()
    From: aperson@example.com
    <BLANKLINE>
    An important message.
    <BLANKLINE>
    >>> msgdata
    {'approved': True}


Suspicious headers
------------------

Suspicious headers are a way for Mailman to hold messages that match a
particular regular expression.  This mostly historical feature is fairly
confusing to users, and the list attribute that controls this is misnamed.

    >>> mlist.bounce_matching_headers = u'From: .*person@(blah.)?example.com'
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ... To: _xtest@example.com
    ... Subject: An implicit message
    ... 
    ... """)
    >>> process(mlist, msg, {})
    Traceback (most recent call last):
    ...
    SuspiciousHeaders
    >>> clear()

But if the header doesn't match the regular expression, it'll get posted just
fine.  This one comes from a .org address.

    >>> msg = message_from_string("""\
    ... From: aperson@example.org
    ... To: _xtest@example.com
    ... Subject: An implicit message
    ... 
    ... """)
    >>> msgdata = {}
    >>> process(mlist, msg, msgdata)
    >>> print msgdata
    {}

Just a bit of clean up.

    >>> mlist.bounce_matching_headers = None


Message size
------------

Mailman can hold messages that are bigger than a given size.  Generally this
is used to prevent huge attachments from getting posted to the list.  This
value is calculated in terms of KB (1024 bytes).

    >>> mlist.max_message_size = 1
    >>> one_line = 'x' * 79
    >>> big_body = '\n'.join([one_line] * 15)
    >>> msg = message_from_string("""\
    ... From: aperson@example.com
    ... To: _xtest@example.com
    ...
    ... """ + big_body)
    >>> process(mlist, msg, {})
    Traceback (most recent call last):
    ...
    MessageTooBig
    >>> clear()


X Hold Notifications
X ------------------
X 
X Whenever Mailman holds a message, it sends notifications both to the list
X owner and to the original sender, as long as it is configured to do so.  We
X can show this by first holding a message.
X 
X     >>> mlist.respond_to_post_requests = True
X     >>> mlist.admin_immed_notify = True
X     >>> msg = message_from_string("""\
X     ... From: aperson@example.com
X     ...
X     ... """)
X     >>> process(mlist, msg, {})
X     Traceback (most recent call last):
X     ...
X     ImplicitDestination
X 
X There should be two messages in the virgin queue, one to the list owner and
X one to the original author.
X 
X     >>> len(switchboard.files)
X     2
X     >>> qfiles = {}
X     >>> for filebase in switchboard.files:
X     ...     qmsg, qdata = switchboard.dequeue(filebase)
X     ...     switchboard.finish(filebase)
X     ...     qfiles[qmsg['to']] = qmsg, qdata
X     >>> qmsg, qdata = qfiles['_xtest-owner@example.com']
X     >>> print qmsg.as_string()
X     Subject: _xtest post from aperson@example.com requires approval
X     From: _xtest-owner@example.com
X     To: _xtest-owner@example.com
X     MIME-Version: 1.0
X     Content-Type: multipart/mixed; boundary="..."
X     Message-ID: ...
X     Date: ...
X     Precedence: bulk
X     <BLANKLINE>
X     --...
X     Content-Type: text/plain; charset="us-ascii"
X     MIME-Version: 1.0
X     Content-Transfer-Encoding: 7bit
X     <BLANKLINE>
X     As list administrator, your authorization is requested for the
X     following mailing list posting:
X     <BLANKLINE>
X         List:    _xtest@example.com
X         From:    aperson@example.com
X         Subject: (no subject)
X         Reason:  Message has implicit destination
X     <BLANKLINE>
X     At your convenience, visit:
X     <BLANKLINE>
X         http://lists.example.com/admindb/_xtest@example.com
X     <BLANKLINE>
X     to approve or deny the request.
X     <BLANKLINE>
X     --...
X     Content-Type: message/rfc822
X     MIME-Version: 1.0
X     <BLANKLINE>
X     From: aperson@example.com
X     Message-ID: ...
X     X-Message-ID-Hash: ...
X     <BLANKLINE>
X     <BLANKLINE>
X     --...
X     Content-Type: message/rfc822
X     MIME-Version: 1.0
X     <BLANKLINE>
X     Content-Type: text/plain; charset="us-ascii"
X     MIME-Version: 1.0
X     Content-Transfer-Encoding: 7bit
X     Subject: confirm ...
X     Sender: _xtest-request@example.com
X     From: _xtest-request@example.com
X     Date: ...
X     Message-ID: ...
X     <BLANKLINE>
X     If you reply to this message, keeping the Subject: header intact,
X     Mailman will discard the held message.  Do this if the message is
X     spam.  If you reply to this message and include an Approved: header
X     with the list password in it, the message will be approved for posting
X     to the list.  The Approved: header can also appear in the first line
X     of the body of the reply.
X     --...
X     >>> sorted(qdata.items())
X     [('_parsemsg', False), ('listname', u'_xtest@example.com'),
X      ('nodecorate', True), ('received_time', ...),
X      ('recips', [u'_xtest-owner@example.com']),
X      ('reduced_list_headers', True),
X      ('tomoderators', 1), ('version', 3)]
X     >>> qmsg, qdata = qfiles['aperson@example.com']
X     >>> print qmsg.as_string()
X     MIME-Version: 1.0
X     Content-Type: text/plain; charset="us-ascii"
X     Content-Transfer-Encoding: 7bit
X     Subject: Your message to _xtest awaits moderator approval
X     From: _xtest-bounces@example.com
X     To: aperson@example.com
X     Message-ID: ...
X     Date: ...
X     Precedence: bulk
X     <BLANKLINE>
X     Your mail to '_xtest' with the subject
X     <BLANKLINE>
X         (no subject)
X     <BLANKLINE>
X     Is being held until the list moderator can review it for approval.
X     <BLANKLINE>
X     The reason it is being held:
X     <BLANKLINE>
X         Message has implicit destination
X     <BLANKLINE>
X     Either the message will get posted to the list, or you will receive
X     notification of the moderator's decision.  If you would like to cancel
X     this posting, please visit the following URL:
X     <BLANKLINE>
X         http://lists.example.com/confirm/_xtest@example.com/...
X     <BLANKLINE>
X     <BLANKLINE>
X     >>> sorted(qdata.items())
X     [('_parsemsg', False), ('listname', u'_xtest@example.com'),
X      ('nodecorate', True), ('received_time', ...),
X      ('recips', [u'aperson@example.com']),
X      ('reduced_list_headers', True), ('version', 3)]
X 
X In addition, the pending database is holding the original messages, waiting
X for them to be disposed of by the original author or the list moderators.  The
X database is essentially a dictionary, with the keys being the randomly
X selected tokens included in the urls and the values being a 2-tuple where the
X first item is a type code and the second item is a message id.
X 
X     >>> import re
X     >>> cookie = None
X     >>> qmsg, qdata = qfiles['aperson@example.com']
X     >>> for line in qmsg.get_payload().splitlines():
X     ...     mo = re.search('confirm/[^/]+/(?P<cookie>.*)$', line)
X     ...     if mo:
X     ...         cookie = mo.group('cookie')
X     ...         break
X     >>> data = config.db.pendings.confirm(cookie)
X     >>> sorted(data.items())
X     [(u'id', ...), (u'type', u'held message')]
X 
X The message itself is held in the message store.
X 
X     >>> rkey, rdata = config.db.requests.get_list_requests(mlist).get_request(
X     ...     data['id'])
X     >>> msg = config.db.message_store.get_message_by_id(
X     ...     rdata['_mod_message_id'])
X     >>> print msg.as_string()
X     From: aperson@example.com
X     Message-ID: ...
X     X-Message-ID-Hash: ...
X     <BLANKLINE>
X     <BLANKLINE>
X  
X Clean up.
X 
X     >>> clear()