1 files changed, 76 insertions, 0 deletions
diff --git a/src/mailman/docs/mlist-addresses.txt b/src/mailman/docs/mlist-addresses.txt
new file mode 100644
index 000000000..75ec3df37
--- /dev/null
+++ b/src/mailman/docs/mlist-addresses.txt
@@ -0,0 +1,76 @@
+Mailing list addresses
+======================
+
+Every mailing list has a number of addresses which are publicly available.
+These are defined in the IMailingListAddresses interface.
+
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+
+The posting address is where people send messages to be posted to the mailing
+list.  This is exactly the same as the fully qualified list name.
+
+    >>> mlist.fqdn_listname
+    u'_xtest@example.com'
+    >>> mlist.posting_address
+    u'_xtest@example.com'
+
+Messages to the mailing list's 'no reply' address always get discarded without
+prejudice.
+
+    >>> mlist.no_reply_address
+    u'noreply@example.com'
+
+The mailing list's owner address reaches the human moderators.
+
+    >>> mlist.owner_address
+    u'_xtest-owner@example.com'
+
+The request address goes to the list's email command robot.
+
+    >>> mlist.request_address
+    u'_xtest-request@example.com'
+
+The bounces address accepts and processes all potential bounces.
+
+    >>> mlist.bounces_address
+    u'_xtest-bounces@example.com'
+
+The join (a.k.a. subscribe) address is where someone can email to get added to
+the mailing list.  The subscribe alias is a synonym for join, but it's
+deprecated.
+
+    >>> mlist.join_address
+    u'_xtest-join@example.com'
+    >>> mlist.subscribe_address
+    u'_xtest-subscribe@example.com'
+
+The leave (a.k.a. unsubscribe) address is where someone can email to get added
+to the mailing list.  The unsubscribe alias is a synonym for leave, but it's
+deprecated.
+
+    >>> mlist.leave_address
+    u'_xtest-leave@example.com'
+    >>> mlist.unsubscribe_address
+    u'_xtest-unsubscribe@example.com'
+
+
+Email confirmations
+-------------------
+
+Email confirmation messages are sent when actions such as subscriptions need
+to be confirmed.  It requires that a cookie be provided, which will be
+included in the local part of the email address.  The exact format of this is
+dependent on the VERP_CONFIRM_FORMAT configuration variable.
+
+    >>> mlist.confirm_address('cookie')
+    u'_xtest-confirm+cookie@example.com'
+    >>> mlist.confirm_address('wookie')
+    u'_xtest-confirm+wookie@example.com'
+
+    >>> config.push('test config', """
+    ... [mta]
+    ... verp_confirm_format: $address---$cookie
+    ... """)
+    >>> mlist.confirm_address('cookie')
+    u'_xtest-confirm---cookie@example.com'
+    >>> config.pop('test config')