Introduction
============
This is a preview version of ZMailIn, which allows you to email into Zope.
Each email that is sent to a particular address causes a document to be 
created in the ZODB with the mail contents.


License
=======
Copyright (c) 2000 New Information Paradigms Ltd. http://www.nipltd.com/
All rights reserved.  

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 
1. Redistributions of source code must retain the above copyright 
   notice, this list of conditions and the following disclaimer. 
2. Redistributions in binary form must reproduce the above copyright 
   notice, this list of conditions and the following disclaimer in the 
   documentation and/or other materials provided with the distribution. 
3. The name of the author may not be used to endorse or promote products 
   derived from this software without specific prior written permission 

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
  
 In accordance with the license provided for by the software upon 
 which some of the source code has been derived or used, the following  
 acknowledgement is hereby provided : 

     "This product includes software developed by Digital Creations 
     for use in the Z Object Publishing Environment 
     (http://www.zope.org/)." 


Status
======
This code is pre-release, and has been lightly tested. Its intended for people
who are curious about how this work is progressing and/or want to have input into
the design process.

We've split the problem into a number of aspects:
  - getting the email from the mail system into a world we can program (Python)
  - getting the mail into Zope
  - figuring out what to do with the mail once it is in Zope

As we are targetting Unix (specifically Linux) we can get the MTA (Exim, or
Sendmail, or most other MTAs) to send mail for a particular address to a script.
This script then scans a text file for the location of a ZMailIn Client
that has been configured to except messages from an email address.  It then
communicates with the Zope product (ZMailIn) via xml-rpc and calls one of the
Products functions which creates an instance of a Python Product (ZMailMessage),
in the folder structure year/month/day, containing the email contents.

At the moment things are all very simple, and most of what should be
configuration is in fact hard coded - the intention at this stage is to get
something working. The remaining work is to:
  - deconstruct the email into its bits (attachments, multipart MIME, etc.)
  - allow different email address to call different DTML methods.
  - allow ZMailIn Clients to be copied, moved, renamed, etc.

This setup has been developed and lightly tested using:
  - Zope 2.1.6 running on Linux (RedHat 6.1)
  - Exim 3.14 as the mail transport. You can find more information about Exim at
    http://www.exim.org/. We believe it should also work with sendmail (the MTA
    normally found on Linux) but haven't tested it


Contents
========
ZMailIn is provided as a single tar archive, ZMailIn-0-3-0.tgz. It comprises
2 Python Products:

	ZMailIn:
		You should have 9 files:
		  - README.txt, a descriptive text file about the ZMailIn Product
		  - ZMailIn.py, the ZMailIn Products main Python File
		  - ZMailInAdd.dtml, The dtml document you see when adding a new ZMailIn 
		    Client
		  - ZMailInEdit.dtml, The dtml document you see when editing a ZMailIn 
		    Client
		  - __init__.py, The init code for the Python Product
		  - index.dtml, The default view for ZMailIn Instances
		  - mailin.png, The graphic that appears next to ZMailIn Instances.
		  - version_control.txt, A history of ZMailIn
		  - sample_mailin_method.txt, An example of a mailin method

	ZMailMessage:
		You should have 13 files:
		  - README.txt, a descriptive text file about the ZMailMessage Product
		  - ZMailMessage.py, the ZMailMessage Products main Python File
		  - ZMailMessageAdd.dtml, The dtml document you see when adding a new 
		    ZMailMessage Client
		  - ZMailMessageEdit.dtml, The dtml document you see when editing a 
		    ZMailMessage Client
		  - __init__.py, The init code for the Python Product
		  - index.dtml, The default view for ZMailMessage Instances
		  - mail.png, The graphic that appears next to ZMailMessage Instances.
		  - version_control.txt, A history of ZMailMessage
		  - zopeMailIn.py, the Python code called by the mail system when a mail 
		    arrives
		  - zopeMailIn.Conf, The zopeMailIn.py configuration
		  - xmlrpc_handler.py |
		  - xmlrpclib.py      |- this is XML-RPC lib v.0.9.8 but with added  
		  - xmlrpcserver.py   |  authentication (thanks to itamar)
	  
	  
Installation
============
(in the following instructions, #zopedir# means your Zope directory, for
example, /usr/local/zope)


1. Extract the ZMailIn-0-3-0.tgz to your Zope directory using

				tar zxvf ZMailIn-0-3-0.tgz
				

2. Configure the #zopedir#/lib/python/Products/ZMailMessage/zopeMailInConf.py
file for your server settings

3. Change the first line of
#zopedir#/lib/python/Products/ZMailMessage/zopeMailIn.py to reflect your python
location ("whereis python").

4. Make sure your MTA has permission to execute zopeMailIn.py. To check
   this, try it, for example if your MTA runs as the user mail, do "su - mail" 
   and then "./zopeMailInPost.py"

     chmod a+x zopeMailInPost.py
   Should fix any access problems, but don't forget to give your MTA permission
   to access the directory #zopedir#/lib/python/Products/ZMailMessage/ as well

5. Make sure your MTA (in our case, Exim) will deliver email to a program. For
   Exim this means assuming Exim is installed and working you need to:
      a. Make sure that pipe transports are enabled.
          - Check /etc/exim.conf for a section in transports like:
          
                  address_pipe:
                    driver = pipe
                    user = mail
                    return_output

            (This is usually there in the default exim.conf file.)
		Add to it the line:
			  envelope_to_add = true
	      (This is important for making ZMailIn work this mailing lists.
		 With Exim this forces Exim to add the 'envelope-to' to the headers
		 of the mail message)

      b. Make sure that there is a director set up to handle pipes. This will 
         be in the same config file in the Directors section and will look
         something like:

                  pipe_transport = address_pipe

         Again, this is already there in a default setup.

      c. Make sure that local_domains is configured to deliver local mail to 
         the host machine. So, if your mail addresses are of the form 
         recipient@foo.bar.baz then you should have

                  local_domains = foo.bar.baz

	d. Restart Exim
  (it may be this step is not needed for machines using Sendmail)


6. In the file /etc/aliases set up the appropriate pipe alias.  e.g. a line
   such as

        recipient:    "|#zopedir#/lib/python/Products/ZMailMessage/zopeMailIn.py"

7. Restart Zope.

8. Create a ZMailIn instance in Zope
   Supply the email of the account you will be suppling emails to.
   Supply the id of the method that will deal with message arrivals
   (Note: Using Mailing Lists
      You must configure your mail program to supply the 'envelope-to' in the headers
	of the mail message.  You must do this for several reasons.
		With a mailing list the arriving mail will have mail@list.com
		in the 'to' header of the mail, not your address

		People can send a message to bob@bobsplace.com and cc or bcc it to
		mail@list.com. This means the 'to' header will contain bob@bobsplace.com

		The 'envelope-to' header (supplied by your mail server) will always
		contain your email address. And as the ZMailIn clients need this
		information it is very important.
    )

9. Create a mailIn Method to handles messages as the arrive in the system.
   When this method is called there will be an attribute called 'theMail' in
   the namespace.  'theMail' is a dictionary containing all the information about
   the mail message, inculding a dictionary of file attachments.
   
   Or you could use the sample method supplied in sample_mailin_method.txt

10.Send a mail to the above address (for example recipient@foo.bar.baz) and
   it should appear in Zope.... 
   

Help
====
This was written by a number of people at NIP. For help with this preview release
contact Andy Dawkins <andyd@nipltd.com>, but don't be surprised if you get a response
from someone else :-)

