1 files changed, 56 insertions, 0 deletions
diff --git a/src/mailman/mta/docs/authentication.txt b/src/mailman/mta/docs/authentication.txt
new file mode 100644
index 000000000..9f494be61
--- /dev/null
+++ b/src/mailman/mta/docs/authentication.txt
@@ -0,0 +1,56 @@
+===================
+SMTP authentication
+===================
+
+The SMTP server may require authentication.  Mailman supports setting the SMTP
+user name and password.  When the user name and password match what's expected
+by the server, everything is a-okay.
+
+    >>> mlist = create_list('test@example.com')
+
+By default there is no user name and password, but this matches what's
+expected by the test server.
+
+    >>> config.push('auth', """
+    ... [mta]
+    ... smtp_user: testuser
+    ... smtp_pass: testpass
+    ... """)
+
+Attempting delivery first must authorize with the mail server.
+::
+
+    >>> from mailman.mta.bulk import BulkDelivery
+    >>> bulk = BulkDelivery()
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: test@example.com
+    ... Subject: My first post
+    ... Message-ID: <first>
+    ...
+    ... First post!
+    ... """)
+
+    >>> bulk.deliver(mlist, msg, dict(recipients=['bperson@example.com']))
+    {}
+
+    >>> print smtpd.get_authentication_credentials()
+    PLAIN AHRlc3R1c2VyAHRlc3RwYXNz
+    >>> config.pop('auth')
+
+But if the user name and password does not match, the connection will fail.
+
+    >>> config.push('auth', """
+    ... [mta]
+    ... smtp_user: baduser
+    ... smtp_pass: badpass
+    ... """)
+
+    >>> bulk = BulkDelivery()
+    >>> response = bulk.deliver(
+    ...     mlist, msg, dict(recipients=['bperson@example.com']))
+    >>> dump_msgdata(response)
+    bperson@example.com: (571, 'Bad authentication')
+
+    >>> config.pop('auth')