# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1389548355 -3600
# Node ID 9da23ddb01404f78b7e3a3f18271432b0968b62d
# Parent  6bd75f8d2ab932c4a9a6ddd79e247d80667816ee
Added some documentation describing the message fetching formats and commands.

diff -r 6bd75f8d2ab9 -r 9da23ddb0140 README.txt
--- a/README.txt	Sun Jan 12 18:12:22 2014 +0100
+++ b/README.txt	Sun Jan 12 18:39:15 2014 +0100
@@ -485,6 +485,57 @@
 representations. Alternatively, a single message part may describe a single
 representation.
 
+The Message Fetching Request and Response Formats
+-------------------------------------------------
+
+Requests made to fetch or manipulate messages via the FetchMessages action or
+equivalent service should have the text/x-moinmessage-fetch content type and
+contain a newline separated sequence of commands resembling those described in
+the POP3 specification (RFC 1939). However, the actual commands supported are
+as follows:
+
+STAT                            return the number of accessible messages
+
+RETR [ <number to retrieve> ]   retrieve the given number of messages
+                                (starting from the first message in the store)
+                                or all messages if the number is omitted
+
+DELE [ <number to delete> ]     delete the given number of messages (starting
+                                from the first message in the store) or all
+                                messages if the number is omitted
+
+Additional commands may be implemented in future. Note that the transactional
+commands in POP3 are not supported since the protocol is not intended to be
+used interactively and there is no notion of a session that is preserved over
+many requests.
+
+Requests should be signed and encrypted in order to preserve the privacy of
+the requester and the nature of their request.
+
+Responses to such requests should have the text/x-moinmessage-fetch-response
+content type and contain a complete message in the response body that should
+be the result of signing and encrypting a response message. (The inclusion of
+an entire message in the body is intended to work around HTTP limitations,
+even though HTTP should really be - or have been - MIME compatible.)
+
+The response message (before signing and encryption) is a multipart/mixed
+message constructed similarly to collections of message updates. Each part of
+this multipart message contains either a command result or a retrieved
+message.
+
+Command results should have the text/x-moinmessage-fetch-result content type
+providing the following headers:
+
+Request-Type                    the command that was provided
+Request-Status                  the status of the command (OK or ERR)
+
+Any specific result value may be provided as the payload of the command result
+message part.
+
+Retrieved messages should have the multipart/mixed content type and provide a
+retrieved message in each part, where such messages may themselves be signed
+or encrypted message representations.
+
 HTTP Methods
 ------------