Introduction

    This is the first release version of CMFMailIn, which allows you to
    email into CMF.  Each email that is sent to known CMF instance
    arrives in the CMF ready to be processed by your own methods or scripts.
    

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.
    There are also unittests for the CMFMailIn Tool and the MailMessage
    content type.
    It is intended for people who wish to be able to get emails in to their own
    CMF Instances.

    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 CMF.
      
      - Figuring out what to do with the mail once it is in CMF.
      
    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.
    
    The setup has been developed and lightly tested using:
    
      - Zope 2.5.1 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

    CMFMailIn is provided as a single tar archive. It contains the
    CMFMailIn Tool, MailMessage Content Type and sendMailToZope.py script


Installation

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


    1. Extract CMFMailIn-*.tgz to your Zope_Home directory using
       *tar zxvf CMFMailIn-*.tgz*	          
       
    2. Change the first line of
       *Zope_Home/lib/python/Products/CMFMailIn/sendMailToZope.py*
       to reflect your python location (*whereis python*).

    3. Make sure your MTA has permission to execute sendMailToZope.py

       To check this, try it, for example if your MTA runs as the user
       mail, do 
       *su - mail* 
       and then
       *./sendMailToZope.py*
  
       *chmod a+x sendMailToZope.py*
       should fix any access problems, but don't forget to give your MTA
       permission to access the directory
       *Zope_Home/lib/python/Products/CMFMailIn/*
       as well.

    4. 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 CMFMailIn 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).

    5. In the file /etc/aliases set up the appropriate pipe alias.
       You also need to supply the location of your CMF instance as the
       first arguement to this method.  You will need to include any
       username and password authentication.

       For example - a line such as::

           recipient:   "|Zope_Home/lib/python/Products/CMFMailIn/sendMailToZope.py http://username:password@www.myserver.com/CMFInstance/"
          
    6. Restart Zope.

    7. Create a CMFMailIn Tool in you CMF Site.
      
       From the add list select "CMFMailIn Tool".
       Then Tick "CMFMail In Tool" and Click 'Add'
    
    8. Add the CMFMailIn skins to your portal_skins tool
    
       In the portal_skins tool, select from the add list 
       "Filesystem Directory View"
       
       In the 'directory' field select "Products/CMFMailIn/skins/mailin",
       leave the 'id' field empty and click 'add'
    
    9. Add the MailMessage content type to your portal_types
    
       In the portal_types tool, select from the add list
       "Factory-based Type Information"
       
       Leave the 'id' field blank and in the 'use default type information'
       field select 'CMFMailIn: CMFMailMessage', then click 'add'
    
   10. In the 'mailin' skin there is a default method that will handle all
       mail messages coming in to the CMF Instance.
       
       This method is called 'mail_received'.
       
       The default mail_received method will take the local part of the
       destination email address of the mail message.
       (i.e. the localpart of 'andyd@nipltd.com' is 'andyd')
       It will look for a Member Folder with the id equal to this localpart.
       If it finds the member folder it will create a MailMessage content
       type instance in the member folder with the id equal to the mail message's
       message-id header, and the content of the file will be the content of
       the email.

       You can, and i advise you to write your own mail_received script that
       will handle the incoming mail messages in a way that you see fit.
       
   11. To test the system send a mail to the address that you have configured
       in your MTA.
       (for example recipient@foo.bar.baz) and it should appear in your CMF.

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