--- a/pyforge/docs/guides/email.rst
+++ b/pyforge/docs/guides/email.rst
@@ -1,2 +1,97 @@
Guide to email integration in the PyForge
-=====================================================================+=====================================================================
+
+Email routing
+---------------------------------------------------------------------
+
+routing mechanism will be a dotted path from the project to
+the application/plugin to the specific artifact within that app that is
+used like this::
+
+ subproject.app.artifact@project.example.com
+
+Which would translate into the devtools project which is a subproject of
+turbogears, and it's bug tracer and issue 142 in that tracker::
+
+ devtools.bug.142@turbogears.sf.net
+
+
+And it in turn would be published to any reactor-plugins that listen on::
+
+ turbogears.*
+ turbogears.devtools.*
+ turbogears.devtools.bug.*
+
+If your app has more than one artifact type, you could nest them inside
+`project.app.something.id.*`
+
+If you were working with the bug tracker directly on the TurboGears project::
+
+ bug.142@turbogears.sf.net
+
+The PyForge platform allows you to setup other message types, such as commit
+messages, to go into amqp with the same routing information, and turn into
+"messages" just like e-mail.
+
+Jon and Wolf have basically already created the routing for this stuff, and
+an amqp based message bus on which e-mail message contents can be placed.
+
+Email Content Handling
+---------------------------------------------------------------------
+
+On the new forge message bodies should be composed as markdown.
+Multi-part mime encoded messages should be sent include plain text
+(the markdown) and html (rendered from the markdown).
+
+Users are allowed to register that they want plain text only.
+
+The html2text tool written in python was offered as a way to turn HTML
+formatted e-mails that we recieve into plain text that is formatted in a
+markdown compatible way. We will have to investigate this a bit more, but it
+looks like a great idea.
+
+We discussed using a special syntax and set of lines at the top of the
+message to indicate metadata::
+
+ Title: My Document
+ Summary: A brief description of my document.
+ Authors: Waylan Limberg, John Doe
+ Date: October 2, 2007
+ base_url: http://example.com
+
+ This is the first paragraph of the document.
+
+The format for this syntax was developed in our original PyForge requirements
+doc, and is pretty much exactly the same as what's used by an existing
+markdown extension (markdown-meta), so with two independent implementations,
+we decided that it was the "natural" way to report metadata in e-mail message
+bodies.
+
+We will also include some text in the footer of the e-mail message with a
+link to the message online. We can use this link to guess where in the
+thread the message belongs in the case of a messed up e-mail client that
+does not set the the headers for the reply properly.
+
+The nice thing about this is that it's pretty much already implemented
+for us via the meta plugin.
+
+This metadata syntax will let you set fields on tickets and otherwise
+interact with the system via e-mail, assuming you have such permissions.
+
+Spam
+---------------------------------------------------------------------
+
+A production deployment of PyForge is likely to have some spam pre-filtering
+applied as a first layer of spam defense. The second layer will be some
+in-app bayesian filtering done inside the Lamson python server that's
+included in PyForge itself.
+
+We'll build a web UI where user feedback can be turned into data that
+feeds back to the bayesian filter training. We will also have to build some
+level of user moderation into the system, based on what's done at slashdot
+already.
+
+Spam prevention technology is a rabbit hole down which the PyForge could go
+forever, without finding a prefect solution. The goal for launch is not
+perfection, but a solid foundation on which future anti-spam measures
+can be taken.