1 files changed, 75 insertions, 0 deletions
diff --git a/src/mailman/queue/docs/outgoing.txt b/src/mailman/queue/docs/outgoing.txt
new file mode 100644
index 000000000..6722dee84
--- /dev/null
+++ b/src/mailman/queue/docs/outgoing.txt
@@ -0,0 +1,75 @@
+Outgoing queue runner
+=====================
+
+The outgoing queue runner is the process that delivers messages to the
+directly upstream SMTP server.  It is this external SMTP server that performs
+final delivery to the intended recipients.
+
+Messages that appear in the outgoing queue are processed individually through
+a 'delivery module', essentially a pluggable interface for determining how the
+recipient set will be batched, whether messages will be personalized and
+VERP'd, etc.  The outgoing runner doesn't itself support retrying but it can
+move messages to the 'retry queue' for handling delivery failures.
+
+    >>> from mailman.app.lifecycle import create_list
+    >>> mlist = create_list(u'test@example.com')
+
+    >>> from mailman.app.membership import add_member
+    >>> from mailman.interfaces.member import DeliveryMode
+    >>> add_member(mlist, u'aperson@example.com', u'Anne Person',
+    ...            u'password', DeliveryMode.regular, u'en')
+    >>> add_member(mlist, u'bperson@example.com', u'Bart Person',
+    ...            u'password', DeliveryMode.regular, u'en')
+    >>> add_member(mlist, u'cperson@example.com', u'Cris Person',
+    ...            u'password', DeliveryMode.regular, u'en')
+
+By setting the mailing list to personalize messages, each recipient will get a
+unique copy of the message, with certain headers tailored for that recipient.
+
+    >>> from mailman.interfaces.mailinglist import Personalization
+    >>> mlist.personalize = Personalization.individual
+    >>> commit()
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: My first post
+    ... Message-ID: <first>
+    ...
+    ... First post!
+    ... """)
+
+Normally, messages would show up in the outgoing queue after the message has
+been processed by the rule set and pipeline.  But we can simulate that here by
+injecting a message directly into the outgoing queue.
+
+    >>> msgdata = {}
+    >>> handler = config.handlers['calculate-recipients']
+    >>> handler.process(mlist, msg, msgdata)
+
+    >>> outgoing_queue = config.switchboards['out']
+    >>> ignore = outgoing_queue.enqueue(
+    ...     msg, msgdata,
+    ...     verp=True, listname=mlist.fqdn_listname, tolist=True,
+    ...     _plaintext=True)
+
+Running the outgoing queue runner processes the message, delivering it to the
+upstream SMTP, which happens to be our test server.
+
+    >>> from mailman.queue.outgoing import OutgoingRunner
+    >>> from mailman.testing.helpers import make_testable_runner
+    >>> outgoing = make_testable_runner(OutgoingRunner, 'out')
+    >>> outgoing.run()
+
+Three messages have been delivered to our SMTP server, one for each recipient.
+
+    >>> from operator import itemgetter
+    >>> messages = sorted(smtpd.messages, key=itemgetter('sender'))
+    >>> len(messages)
+    3
+
+    >>> for message in messages:
+    ...     print message['sender']
+    test-bounces+aperson=example.com@example.com
+    test-bounces+bperson=example.com@example.com
+    test-bounces+cperson=example.com@example.com