--- a/pyforge/docs/platform_tour.rst
+++ b/pyforge/docs/platform_tour.rst
@@ -238,5 +238,67 @@
:param message: optional dictionary with message content
:param kw: optional keyword arguments which are passed through to the `carrot.Publisher`
-
-
+Email Integration
+-----------------------------------------
+
+The Forge platform provides easy-to-use email integration. Forge email addresses
+are of the form
+<topic>@<mount_point>[.<subproject>]*.<subproject>.projects.sourceforge.net.
+When a message is received on such an email address, the address is parsed and
+the sending user is identified (if possible). Based on the parsed address, the
+pylons context attributes `c.project` and `c.app` are set, and the application is
+queried to determine whether the identified user has authority to send an email
+to the given app/topic combination by calling `c.app.has_access(user, topic)`.
+If the user has access, the message is decomposed into its component parts (if a
+multipart MIME-encoded message) and one `audit` message is generated for each
+part with the following fields:
+
+headers
+ The actual headers parsed from the body of the message
+message_id
+ The `Message-ID` header (which should be universally
+ unique and is
+ generated by the email client), used for determining which messages are replies
+ to which other messages
+in_reply_to
+ The `In-Reply-To` header, used for determining which messages are replies to
+ which other messages
+references
+ The `References` header, used for determining which messages refer to
+ which other messages
+filename
+ Optional, if the part is an attachment with a filename, this will be populated
+content_type
+ The MIME content_type of the message part
+payload
+ The actual content of the message part
+user_id
+ The ID of the user who sent the message
+
+Once the message is generated, it is sent to the `audit` exchange with the
+routing key <Plugin Type>.<topic>. For instance, a message to comment on a Wiki
+page might have the routing key `Wiki.MainPage`.
+
+The Forge platform also provides full support for *sending* email without
+worrying about the specifics of SMTP or sendmail handling. In order to send an
+email, a plugin needs simply to send an `audit` message with the routing key
+`forgemail.send_email` and the following fields:
+
+from
+ Return address on the message (usually the topic@plugin_name that generated
+ it)
+subject
+ Subject of the message
+message_id
+ Value to put in the `Message-ID` header (the `_id` field of a
+ :class:`pyforge.model.artifact.Message` is suitable for this)
+in_reply_to (optional)
+ Value to put in the `In-Reply-To` header (the `parent_id` field of a
+ :class:`pyforge.model.artifact.Message` is suitable for this)
+destinations
+ List of email addresses and/or :class:`pymongo.bson.ObjectId` s for
+ :class:`pyforge.model.auth.User` objects
+text
+ Markdown-formatted body of the message (If the user has requested html or
+ combined text+html messages in their preferences, the Markdown will be so
+ rendered. Otherwise a plain text message will be sent.)