Add page explaining holding pen, update links in glossary and admin_guide

2 files changed, 99 insertions, 0 deletions

diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index dbe8be3d1..3b05a5400 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -367,6 +367,12 @@ message under the title *Things to do*:
 Click on that message — you'll see a list of all the messages that need
 your attention. Click on any one of them to see the details.
 
+<div class="attention-box helpful-hint">
+  If the message does not belong to any request, you can delete it instead.
+  Simply click on the <strong>Destroy Message</strong> button instead of
+  redelivering it.
+</div>
+
 When you inspect a message, you may see a guess made by Alaveteli as to which
 request the message belongs to. Check this request. If the guess is right
 &mdash; the incoming email really is a response to that request &mdash; 
@@ -404,6 +410,7 @@ 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 
diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md
new file mode 100644
index 000000000..7314b7a6b
--- /dev/null
+++ b/docs/running/holding_pen.md
@@ -0,0 +1,92 @@
+---
+layout: page
+title: The holding pen
+---
+
+#  The holding pen
+
+<p class="lead">
+  
+  The <em>holding pen</em> is where Alaveteli puts any incoming
+  <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a>
+  that can't be matched to a
+  <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a>
+  automatically.
+</p>
+
+
+Alaveteli works by emailing requests to the correct target
+<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a>.
+That email message is sent from a unique email address &mdash; that is, an
+email address that is associated with that single request (technically,
+Alaveteli hashes the request ID to generate a unique address and uses this as
+the `Reply-to:` address).
+
+So whenever an authority replies (by email) to a request that Alaveteli has
+sent, that response will be addressed to that request's unique email address.
+The email is received by your installation's
+<a href="{{ site.baseurl}}docs/glossary/#mta" class="glossary__link">MTA</a>,
+and is passed on to Alaveteli. In this way, incoming messages are easily
+matched with the request they are responses to &mdash; this is important
+because your site displays the responses underneath their original request, on
+the request's page.
+
+Normally, this works fine. But sometimes things go wrong, and a message comes
+in that can't be matched with a request. When this happens, Alaveteli puts the
+message in the
+<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding
+pen </a>.
+
+Messages wait in the holding pen until an 
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>
+redelivers them to the correct request, or else deletes them.
+
+## Why messages end up in the holding pen
+
+There are several reasons why a message might end up in the holding pen:
+
+* **the authority "broke" the reply-to email**<br>
+  This can happen if the authority replies "by hand" to the incoming email &mdash;
+  for example if the person at the authority accidentally loses the first
+  letter of the email address when they copy-and-paste it. Or if they copy
+  it manually and simply get it wrong.
+  
+* **the message is sent to multiple (valid) email addresses**<br>
+  Sometimes an officer working for an authority may attempt to send email using
+  a collection of email addresses for you site. When this happens &mdash;
+  an incoming email is addressed to *more than one* valid email addresses &mdash;
+  Alaveteli will direct it into the holding pen because it cannot decide
+  which, if any, is the correct one.
+
+* **there's something unusual about the way it was sent**<br>
+  For example, if it was delivered here because the address is in the `Bcc:`
+  field, and is not the `To:` address.
+
+* **a partial email address may have been guessed**<br>
+  This may be because someone has guessed an email address either because they
+  have misunderstood how the addresses are formed, or due to a deliberate 
+  attempt to send spam.
+
+## What to do: redeliver or delete
+
+You need to be an
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>
+to modify the holding pen. There are two things you can do to a message in the
+holding pen:
+
+  * **find the right request, and redeliver the message**<br>
+    Alaveteli tries to guess the right request to help you, so sometimes
+    you can just accept its suggestion. 
+    
+  * **delete the message**<br>
+    If the message is not a response, you can delete it.
+
+For instructions, see
+[removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen).
+
+If the message is clearly spam, you can also add its `To:` email address to Alaveteli's
+<a href="{{site.baseurl}}#spam-address-list" class="glossary__link">spam address list</a>.
+Subsequent messages to that address will be automatically rejected &mdash; for
+instructions see
+[rejecting spam that arrives in the holding pen]({{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen).
+