Introduction

    This is the first final release version of ZMailIn, which allows you to
    email into Zope.  Each email that is sent to a particular address
    arrives in the Zope environment ready to be processed by your own methods.
    

Status

    This is a release version and is actually in use by NIP.
    This release has been tested using the eXtreme Programming
    ( "XP":http://www.extremeprogramming.org/ ) methodology
    and NIP's in-house product testing system.
    It is intended for people who wish to be able to get emails in to their own
    Zope environment.

    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 queries a ZCatalog for the location of the ZMailIn Client
    that has been configured to except messages from an email address.  It then
    communicates with the Zope product (ZMailIn), via http post, and calls one
    of the Products functions which pulls the mail message in to useful parts
    before sending it to a specified method.

    The setup has been developed and lightly tested using:
    
      - Zope 2.4.3 running on Linux (Mandrake 8.1).
      - Zope 2.5.0 running on Linux (Mandrake 8.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. It contains the ZMailIn
    Python Products.


Installation

    (In the following instructions, Zope_Home means your Zope directory, for
     example, */usr/local/zope*.)


    1. Extract ZMailIn-1-0-0.tgz to your Zope_Home directory using
       *tar zxvf ZMailIn-1-0-0.tgz*	          

    2. Configure the
       *Zope_Home/lib/python/Products/ZMailIn/zopeMailInConf.py*
       file for your server settings.
       
    3. Change the first line of
       *Zope_Home/lib/python/Products/ZMailIn/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
       *Zope_Home/lib/python/Products/ZMailIn/*
       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 found in the default exim.conf file.
          To make ZMailIn work for mailing lists add this line::
                
                  envelope_to_add = true
                    
          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 present in the 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
          (this step may not be needed for machines running Sendmail).

    6. In the file /etc/aliases set up the appropriate pipe alias.

       For example - a line such as::

           recipient:   "|Zope_Home/lib/python/Products/ZMailIn/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 the following
         in the 'to' header of the mail, not your address::
           
                       mail@list.com
  
       - 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. This is important in finding the correct
         ZMailIn Client.

    9. Create a mailIn Method to handle messages as they 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, including a dictionary of file attachments.
   
       Alternatively you could use the sample method supplied in
       *sample_zmailin_method.zexp*
       This method will create a ZMailMessage object in the same object manager
       as the ZMailIn Client with the id of 'Sample_Email'.
       
       If an email of this id already exists then it will return an error.
       
       This is a Python Script so you will need Zope 2.3.0 or higher.
       
       To import this script copy the file 
       *sample_zmailin_method.zexp*
       to your
       *Zope_Home/import/*
       directory and import it in to your Zope instance.
       
       Then simply point your ZMailIn Client at sample_zmailin_method by
       entering *sample_zmailin_method* in to the method field.

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

Domain Addresses

  ZMailIn will also work for domain address, for example,
  you can set the ZMailIn Client email address to::

      @mydomain.com
  
  Then that ZMailIn Client will handle every message that it gets given by the
  MTA that was addressed to that domain.
  
  For example::
  
      bob@mydomain.com
      sam@mydomain.com
      anyone@mydomain.com
  
  You will have to configure your MTA as required.

Support

  This was written by a number of people at NIP. For help with this release
  contact
  "New Information Paradigms Ltd - ZMailIn Support", mailto:zmailin-support@groups.nipltd.com
