From 135b09cab1aa7f53bd7604d965f3fa0e5c86227d Mon Sep 17 00:00:00 2001
From: Dave Whiteland <dave@mysociety.org>
Date: Tue, 27 Jan 2015 12:13:09 +0000
Subject: add description of spam address list

Note this includes the wish-list "Mark as Spam button" text which
hasn't been implemented yet.
---
 docs/running/admin_manual.md | 50 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

(limited to 'docs/running')

diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index d18c1c8f9..47055d0a7 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -31,6 +31,7 @@ In this guide:
     <ul>
       <li><a href="#administrator-privileges-and-accessing-the-admin-interface">Administrator privileges and accessing the admin interface</a></li>
       <li><a href="#removing-a-message-from-the-holding-pen">Removing a message from the 'Holding Pen'</a></li>
+      <li><a href="#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting spam that arrives in the holding pen</a></li>
       <li><a href="#creating-changing-and-uploading-public-authority-data">Creating, changing and uploading public authority data</a></li>
       <li><a href="#banning-a-user">Banning a user</a></li>
       <li><a href="#deleting-a-request">Deleting a request</a></li>
@@ -403,6 +404,54 @@ another request** button.
 The message will now be associated with the correct request. It is no longer
 in the holding pen, and is shown instead on the public request page.
 
+### Rejecting spam that arrives in the holding pen
+
+Alaveteli maintains a 
+<a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>.
+Any incoming message to an email  address on that list will be rejected and
+won't appear in the admin.
+
+If you see spam messages in the
+<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>,
+check if they are being sent to a *specific* email address. If they are, that
+email address has become a "spam-target" and you should add it to the spam
+address list. Thereafter, Alaveteli will automatically reject any messages that
+come into that address.
+
+An email address that is not associated with a request (that is, one whose
+messages end up in the holding pen) becomes a spam-target once it's been
+harvested by spammers. It may no longer be valid because the request to which
+it belonged has closed, or it may have been mis-spelled in a manual reply.
+Our experience from running
+<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>
+is that you can safely dismiss incoming email to such addresses once they have
+been targetted in this way. Legitimate emails that arrive in the holding pen
+tend to be unique errors (for example, missing the last character of the email
+address due to a cut-and-paste mistake) and the nature of the lifecycle of
+requests means they don't typically get used for spam until they are
+effectively dead.
+
+The easiest way to add such an email address to the spam address list is to do
+so from the incoming message itself. In the admin interface, go to the holding
+pen (click on **Requests** and then **Holding pen**). Under *Incoming Messages*
+click on the message that is spam. Under *Actions*, click on the **Mark as
+spam** button that appears by the `To:` email address.
+
+You can see the spam address list (that is, all known spam-target email
+addresses) by going to the admin interface at `/admin/spam_addresses`. As an
+alternative to using the **Mark as spam** button on the message itself, you can
+manually add any email address there and click **Add spam address**.
+
+You can remove any address from the list by clicking the **Remove** button
+next to it. Of course, this won't restore any messages that have been 
+rejected, but Alaveteli will not reject any new messages that are sent to
+this address.
+
+Note that if you are seeing consistent spam email in your holding pen, you
+should also consider implementing (or increasing) the anti-spam measures
+running in your 
+<a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>.
+
 ### Creating, changing and uploading public authority data
 
 There are three ways to change public authority data on your site:
@@ -719,4 +768,3 @@ text you wish to replace it with e.g. '[personal information has been
 hidden]', and a comment letting other admins know why you have hidden
 the information.
 
-
-- 
cgit v1.2.3