diff options
Diffstat (limited to 'mailman/pipeline/docs/replybot.txt')
| -rw-r--r-- | mailman/pipeline/docs/replybot.txt | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/mailman/pipeline/docs/replybot.txt b/mailman/pipeline/docs/replybot.txt new file mode 100644 index 000000000..2e3765cab --- /dev/null +++ b/mailman/pipeline/docs/replybot.txt @@ -0,0 +1,216 @@ +Auto-reply handler +================== + +Mailman has an auto-reply handler that sends automatic responses to messages +it receives on its posting address, or special robot addresses. Automatic +responses are subject to various conditions, such as headers in the original +message or the amount of time since the last auto-response. + + >>> from mailman.pipeline.replybot import process + >>> from mailman.configuration import config + >>> mlist = config.db.list_manager.create(u'_xtest@example.com') + >>> mlist.real_name = u'XTest' + >>> mlist.web_page_url = u'http://www.example.com/' + + >>> # Ensure that the virgin queue is empty, since we'll be checking this + >>> # for new auto-response messages. + >>> from mailman.queue import Switchboard + >>> virginq = Switchboard(config.VIRGINQUEUE_DIR) + >>> virginq.files + [] + + +Basic autoresponding +-------------------- + +Basic autoresponding occurs when the list is set up to respond to either its +-owner address, its -request address, or to the posting address, and a message +is sent to one of these addresses. A mailing list also has an autoresponse +grace period which describes how much time must pass before a second response +will be sent, with 0 meaning "there is no grace period". + + >>> import datetime + >>> mlist.autorespond_admin = True + >>> mlist.autoresponse_graceperiod = datetime.timedelta() + >>> mlist.autoresponse_admin_text = u'admin autoresponse text' + >>> msg = message_from_string("""\ + ... From: aperson@example.com + ... To: _xtest-owner@example.com + ... + ... help + ... """) + >>> process(mlist, msg, dict(toowner=True)) + >>> len(virginq.files) + 1 + >>> qmsg, qdata = virginq.dequeue(virginq.files[0]) + >>> # Print only some of the meta data. The rest is uninteresting. + >>> qdata['listname'] + u'_xtest@example.com' + >>> sorted(qdata['recips']) + [u'aperson@example.com'] + >>> # Delete data that is time dependent or random + >>> del qmsg['message-id'] + >>> del qmsg['date'] + >>> print qmsg.as_string() + MIME-Version: 1.0 + Content-Type: text/plain; charset="us-ascii" + Content-Transfer-Encoding: 7bit + Subject: Auto-response for your message to the "XTest" mailing list + From: _xtest-bounces@example.com + To: aperson@example.com + X-Mailer: The Mailman Replybot + X-Ack: No + Precedence: bulk + <BLANKLINE> + admin autoresponse text + >>> virginq.files + [] + + +Short circuiting +---------------- + +Several headers in the original message determine whether an autoresponse +should even be sent. For example, if the message has an "X-Ack: No" header, +no auto-response is sent. + + >>> msg = message_from_string("""\ + ... From: aperson@example.com + ... X-Ack: No + ... + ... help me + ... """) + >>> process(mlist, msg, dict(toowner=True)) + >>> virginq.files + [] + +Mailman itself can suppress autoresponses for certain types of internally +crafted messages, by setting the 'noack' metadata key. + + >>> msg = message_from_string("""\ + ... From: mailman@example.com + ... + ... help for you + ... """) + >>> process(mlist, msg, dict(noack=True, toowner=True)) + >>> virginq.files + [] + +If there is a Precedence: header with any of the values 'bulk', 'junk', or +'list', then the autoresponse is also suppressed. + + >>> msg = message_from_string("""\ + ... From: asystem@example.com + ... Precedence: bulk + ... + ... hey! + ... """) + >>> process(mlist, msg, dict(toowner=True)) + >>> virginq.files + [] + + >>> msg.replace_header('precedence', 'junk') + >>> process(mlist, msg, dict(toowner=True)) + >>> virginq.files + [] + >>> msg.replace_header('precedence', 'list') + >>> process(mlist, msg, dict(toowner=True)) + >>> virginq.files + [] + +Unless the X-Ack: header has a value of "yes", in which case, the Precedence +header is ignored. + + >>> msg['X-Ack'] = 'yes' + >>> process(mlist, msg, dict(toowner=True)) + >>> len(virginq.files) + 1 + >>> qmsg, qdata = virginq.dequeue(virginq.files[0]) + >>> del qmsg['message-id'] + >>> del qmsg['date'] + >>> print qmsg.as_string() + MIME-Version: 1.0 + Content-Type: text/plain; charset="us-ascii" + Content-Transfer-Encoding: 7bit + Subject: Auto-response for your message to the "XTest" mailing list + From: _xtest-bounces@example.com + To: asystem@example.com + X-Mailer: The Mailman Replybot + X-Ack: No + Precedence: bulk + <BLANKLINE> + admin autoresponse text + + +Available auto-responses +------------------------ + +As shown above, a message sent to the -owner address will get an auto-response +with the text set for owner responses. Two other types of email will get +auto-responses: those sent to the -request address... + + >>> mlist.autorespond_requests = True + >>> mlist.autoresponse_request_text = u'robot autoresponse text' + >>> msg = message_from_string("""\ + ... From: aperson@example.com + ... To: _xtest-request@example.com + ... + ... help me + ... """) + >>> process(mlist, msg, dict(torequest=True)) + >>> len(virginq.files) + 1 + >>> qmsg, qdata = virginq.dequeue(virginq.files[0]) + >>> del qmsg['message-id'] + >>> del qmsg['date'] + >>> print qmsg.as_string() + MIME-Version: 1.0 + Content-Type: text/plain; charset="us-ascii" + Content-Transfer-Encoding: 7bit + Subject: Auto-response for your message to the "XTest" mailing list + From: _xtest-bounces@example.com + To: aperson@example.com + X-Mailer: The Mailman Replybot + X-Ack: No + Precedence: bulk + <BLANKLINE> + robot autoresponse text + +...and those sent to the posting address. + + >>> mlist.autorespond_postings = True + >>> mlist.autoresponse_postings_text = u'postings autoresponse text' + >>> msg = message_from_string("""\ + ... From: aperson@example.com + ... To: _xtest@example.com + ... + ... help me + ... """) + >>> process(mlist, msg, {}) + >>> len(virginq.files) + 1 + >>> qmsg, qdata = virginq.dequeue(virginq.files[0]) + >>> del qmsg['message-id'] + >>> del qmsg['date'] + >>> print qmsg.as_string() + MIME-Version: 1.0 + Content-Type: text/plain; charset="us-ascii" + Content-Transfer-Encoding: 7bit + Subject: Auto-response for your message to the "XTest" mailing list + From: _xtest-bounces@example.com + To: aperson@example.com + X-Mailer: The Mailman Replybot + X-Ack: No + Precedence: bulk + <BLANKLINE> + postings autoresponse text + + +Grace periods +------------- + +Auto-responses have a grace period, during which no additional responses will +be sent. This is so as not to bombard the sender with responses. The grace +period is measured in days. + +XXX Add grace period tests. |