diff options
Diffstat (limited to 'src/mailman/queue/docs/command.txt')
| -rw-r--r-- | src/mailman/queue/docs/command.txt | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/src/mailman/queue/docs/command.txt b/src/mailman/queue/docs/command.txt new file mode 100644 index 000000000..0b384de01 --- /dev/null +++ b/src/mailman/queue/docs/command.txt @@ -0,0 +1,170 @@ +The command queue runner +======================== + +This queue runner's purpose is to process and respond to email commands. +Commands are extensible using the Mailman plugin system, but Mailman comes +with a number of email commands out of the box. These are processed when a +message is sent to the list's -request address. + + >>> from mailman.app.lifecycle import create_list + >>> mlist = create_list(u'test@example.com') + + +A command in the Subject +------------------------ + +For example, the 'echo' command simply echoes the original command back to the +sender. The command can be in the Subject header. + + >>> msg = message_from_string("""\ + ... From: aperson@example.com + ... To: test-request@example.com + ... Subject: echo hello + ... Message-ID: <aardvark> + ... + ... """) + + >>> from mailman.inject import inject_message + >>> inject_message(mlist, msg, switchboard='command') + >>> from mailman.queue.command import CommandRunner + >>> from mailman.testing.helpers import make_testable_runner + >>> command = make_testable_runner(CommandRunner) + >>> command.run() + +And now the response is in the virgin queue. + + >>> from mailman.queue import Switchboard + >>> virgin_queue = config.switchboards['virgin'] + >>> len(virgin_queue.files) + 1 + >>> from mailman.testing.helpers import get_queue_messages + >>> item = get_queue_messages('virgin')[0] + >>> print item.msg.as_string() + Subject: The results of your email commands + From: test-bounces@example.com + To: aperson@example.com + ... + <BLANKLINE> + The results of your email command are provided below. + <BLANKLINE> + - Original message details: + From: aperson@example.com + Subject: echo hello + Date: ... + Message-ID: <aardvark> + <BLANKLINE> + - Results: + echo hello + <BLANKLINE> + - Done. + <BLANKLINE> + >>> sorted(item.msgdata.items()) + [..., ('listname', u'test@example.com'), ..., + ('recips', [u'aperson@example.com']), + ...] + + +A command in the body +--------------------- + +The command can also be found in the body of the message, as long as the +message is plain text. + + >>> msg = message_from_string("""\ + ... From: bperson@example.com + ... To: test-request@example.com + ... Message-ID: <bobcat> + ... + ... echo foo bar + ... """) + + >>> inject_message(mlist, msg, switchboard='command') + >>> command.run() + >>> len(virgin_queue.files) + 1 + >>> item = get_queue_messages('virgin')[0] + >>> print item.msg.as_string() + Subject: The results of your email commands + From: test-bounces@example.com + To: bperson@example.com + ... + Precedence: bulk + <BLANKLINE> + The results of your email command are provided below. + <BLANKLINE> + - Original message details: + From: bperson@example.com + Subject: n/a + Date: ... + Message-ID: <bobcat> + <BLANKLINE> + - Results: + echo foo bar + <BLANKLINE> + - Done. + <BLANKLINE> + + +Stopping command processing +--------------------------- + +The 'end' command stops email processing, so that nothing following is looked +at by the command queue. + + >>> msg = message_from_string("""\ + ... From: cperson@example.com + ... To: test-request@example.com + ... Message-ID: <caribou> + ... + ... echo foo bar + ... end ignored + ... echo baz qux + ... """) + + >>> inject_message(mlist, msg, switchboard='command') + >>> command.run() + >>> len(virgin_queue.files) + 1 + >>> item = get_queue_messages('virgin')[0] + >>> print item.msg.as_string() + Subject: The results of your email commands + ... + <BLANKLINE> + - Results: + echo foo bar + <BLANKLINE> + - Unprocessed: + echo baz qux + <BLANKLINE> + - Done. + <BLANKLINE> + +The 'stop' command is an alias for 'end'. + + >>> msg = message_from_string("""\ + ... From: cperson@example.com + ... To: test-request@example.com + ... Message-ID: <caribou> + ... + ... echo foo bar + ... stop ignored + ... echo baz qux + ... """) + + >>> inject_message(mlist, msg, switchboard='command') + >>> command.run() + >>> len(virgin_queue.files) + 1 + >>> item = get_queue_messages('virgin')[0] + >>> print item.msg.as_string() + Subject: The results of your email commands + ... + <BLANKLINE> + - Results: + echo foo bar + <BLANKLINE> + - Unprocessed: + echo baz qux + <BLANKLINE> + - Done. + <BLANKLINE> |