Mail Templates

  Note: This is a Nexedi version of MailTemplates, but not the official
  one.

  Mail Templates provide full access to Python's email package and
  allow the body of messages to be generated using Zope's Page
  Template technology. They work in both a Zope environment and a CMF
  environment. That includes software based on the CMF such as Plone
  and CPS.

  If you're impatient and want to get going, skip straight to the
  examples section further on in this document.

  Requirements

    Zope 2.8.0 or higher is required.

  Installation

    Mail Templates should be installed as for any standard Zope
    product. Unpack the tarball into the Products directory of your
    instance home and restart your instance. More extensive
    documentation regarding the installation of Zope Products can be
    found on http://www.zope.org.

  Overview

    Mail Templates can be created either by adding a Mail Template
    using the menu in Zope's management information or by adding a
    file with a .mt extension in a folder pointed to by a File System
    Directory View.

    NB: Due a bug in certain specific versions of Zope 2.7.x, you may
        receive an Unauthorized error while trying to add a
        MailTemplate through the ZMI. If this happens, please update
        to a newer version of Zope.

    Either type of Mail Template is a callable object that, when
    called, renders the body of a mail message and either returns that
    as an object that may have further parts added to it or actually
    uses a configured Mail Host object to send the message.

    Various attributes of the generated mail, such as headers,
    charcater encoding and MIME encoding are controlled by a
    combination of properties on the Mail Template and parameters
    passed to the Mail Template when it is called.

    In addition, the MailTemplates product contains security
    assertions that make all of Python's email package available for
    use in "untrusted" Zope code such as Script (Python) objects.

  Properties

    The following properties can be added to a Mail Template using the
    Properties tab, or an accompanying .metadata file for skin-based
    Mail Templates:

    mailhost

      For ZODB-based Mail Templates, this is set using the drop-down
      on the edit screen. For skin-based Mail Templates, this is
      specified in the .metadata file associated with the Mail Template.
      
      In either case, it ends up being a slash-seperated path that is
      used to traverse to the MailHost object which will be used to
      send email.
      
    content_type

      As well as influencing the ZPT engine, the property is also used
      as the content type for the email generated by this Mail
      Template.

    mfrom

      This should be a string property and should contain the
      address which will be used to generate the 'From' header for any
      mail sent from this Mail Template.
   
    mto

      This should be a string property, for a single address, or a
      lines property for multiple addresses, and should contain the
      address(es) to which any mail generated using this Mail Template
      will be sent. It is also used to generate the 'To' header.
   
    mcc
   
      This should be a string property, for a single address, or a
      lines property for multiple addresses, and should contain the
      address(es) which will be used to generate the 'CC' header for any
      mail sent from this Mail Template.
   
    mbcc
 
      This should be a string property, for a single address, or a
      lines property for multiple addresses, and should contain the
      address(es) which will be used to generate the 'BCC' header for any
      mail sent from this Mail Template.
   
    subject

      This should be a string property and its value will be used to
      generate the 'Subject' header for any mail sent from this Mail
      Template. 
   
    headers 

      This should be a lines property and each line should be of the
      form:
      
      HeaderName: value-to-set

      The headers specified in this property will be added to any mail
      generated by this Mail Template.

    encoding

      This should be a string property and controls the character set
      used to encode any mail generated by this Mail Template. It is
      used for both the character set supplied in the MIME encoding
      and for encoding the results of rending non-html emails. See the
      section on Unicode and Encoded Strings below for more
      information. 

      The default value is that specifed in zope.conf's
      default_zpublisher_encoding setting, if avaiable, or iso-8859-15
      otherwise. 

  Methods

    In addition to being directly callable, Mail Templates have the
    following methods. Directly calling a Mail Template is an alias
    for calling the 'send' method described below. The parameters to
    both methods are described in the Parameters section further down
    in this document.

    send

      This method renders the email and sends it using the configured
      Mail Host. 

    as_message

      This method is used when you want to build multi-part emails
      such as those with both text and html versions and those with
      attached files.

      It renders the body of the MailTemplate as an email.MIMEText
      object, creates a MailTemplates.MTMultipart containing the
      headers for the rendered email, attaches the body to it and
      returns it.

      An MTMultipart object is identical to an email.MIMEMultipart
      object except that is has two additional methods:

      send

        This sends a rendered version of the message described by the
        MTMultipart object using the Mail Host configured in the Mail
        Template that created it.
      
      add_file

        This method is used to add attachments to the message.
        It can take either one parameter or two keyword parameters. 
        In either case, an optional content_type keyword parameter 
        can be specified.
        If one parameter is passed, the it should be a Zope File or Image
        object, ZPublisher FileUpload object or a python file object. 
        If two keyword parameters are passed, they should be 'data'
        and 'filename'. 'data' should be a string containing the body
        of the attachment. 'filename' should be the file name to use
        for the attachment.
        In all cases, the content_type parameter can be used to
        override any guesswork in setting the content type for the
        attachment.

      In addition to the paramters described below, the following
      keyword parameters can also optionally be used to control
      aspects of the multi-part message creation:

      subtype
 
        This is a string argument specifying the subtype to use for
        the content type of the multi part message. The default is
        calculated to be something sensible but could, for example, be
        set to 'alternative' to give a 'multipart/alternative' message.

      boundary

        This is a tring specifying the boundary to use for multi-part
        messages. In general, this should not be specified, but can be
        handy when writing unit tests.

  Parameters

    The following parameter may optionally be passed as keyword
    arguments to both the 'send' and 'as_message' methods:

    mfrom

      This should be a string and should contain the address which
      will be used to generate the 'From' header for the message being
      generated or sent.
   
    mto

      This should be a string, for a single address, or a sequence of
      strings, for multiple addresses and should contain the
      address(es) to which the message will be sent. It is also used
      to generate the 'To' header. 
   
    mcc
   
      This should be a string, for a single address, or a sequence of
      strings, for multiple addresses and should contain the
      address(es) which will be used to generate the 'CC' header for
      the mail currently being generated or sent.
   
    mbcc
 
      This should be a string, for a single address, or a sequence of
      strings, for multiple addresses and should contain the
      address(es) which will be used to generate the 'BCC' header for
      the mail currently being generated or sent.
   
    subject

      This should be a string and will be used to generate the
      'Subject' header for the mail currently being generated or
      sent. 
   
    headers 

      This should be a dictionary mapping header names to header
      values. Both the names and values should be strings.

      The headers specified in this dictionary will be added to the
      mail currently being generated or sent. 
   
    encoding

      This parameter controls the character set used to encode the mail
      currently being generated or sent. It is used for both the
      character set supplied in the MIME encoding and for encoding the
      results of rending non-html emails. See the section on Unicode
      and Encoded Strings below for more information.

      The default value is that specifed in zope.conf's
      default_zpublisher_encoding setting, if avaiable, or iso-8859-15
      otherwise. 

  Precedence During Generation

    When generating an email, headers and the charset, mto and mfrom
    parameters can come from several places; the parameters passed to
    the send or as_message method, the properties of the Mail Template
    itself, or the headers parameter or property. The order lookup is
    as follows:

    1. The parameters passed to the send or as_message method

    2. For headers only, the content of the headers parameter passed
       to the send or as_message method.

    3. The properties of the Mail Template object

    4. For headers only, the content of the headers property of the
       Mail Template object.

  Required Parameters

    In order for a Mail Template to be successfully rendered, the
    following parameters must be obtained through one of the four
    options listed above:

    - mto
    - mfrom
    - subject

    If any of the above parameters cannot be obtained, an exception
    will be raised.    

  Unicode and Encoded Strings

    Please note that you can run into problems with Mail Templates in
    exactly the same way as for normal Page Templates if you attempt
    to insert strings encoded in anything other than us-ascii or
    unicodes that cannot be encoded into us-ascii.

    The way any problematic values should be handles depends on what
    the content_type of your Mail Template is set to:

    If content_type is set to text/html, then:

    - any unicodes should be encoded using the character set you
      intend to use for the final mail encoding

    - you are responsible for ensuring that any strings are encoded
      with the correct character set, which should be that used for
      the final mail encoding.

    If content_type is set to anything else:

    - all string-like data inserted into the Mail Template during
      rendering must be in the form of unicode objects.

    Finally, the encoding property or parameter should match the
    character set you use to encode or decode any string-like objects.

    Here are some simple examples to illustrate correct and incorrect
    usage. While 'encoding' is passed as a parameter here, you may
    find it more convenient to set as a property or, if you are using
    Zope 2.7.8, Zope 2.8.2 or above, but specifying the
    default_zpublisher_encoding in your zope.conf file.

    Bad Example 1:

      Mail Template with content_type set to 'text/plain':

        Your currency is <tal:x replace="options/currency"/>

      Script Python:
  
        return container.test_mt(currency=u'£'.encode('utf-8'),
                                 encoding='utf-8')

      Should have been:

        Your currency is <tal:x replace="python:options.currency.decode('utf-8')"/>

      ...or alternatively:

        return container.test_mt(currency=u'£',
                                 encoding='utf-8')

    Bad Example 2:

      Mail Template with content_type set to 'text/html':

        Your currency is <tal:x replace="options/currency"/>

      Script Python:
  
        return container.test_mt(currency=u'£',
                                 encoding='utf-8')

      Should have been:

        Your currency is <tal:x replace="python:options.currency.encode('utf-8')"/>

      ...or alternatively:

        return container.test_mt(currency=u'£'.encode('utf-8'),
                                 encoding='utf-8')

  Examples

    The following are some simple contrived examples to show some of
    the possible uses of Mail Templates. If you wish to test with
    these, you will need to change the 'mto' addresses.

    Simple Example

      This example sends a simple templated mail to a specific
      address.

      Add the following to a Mail Template called my_mt:

      <tal:body xmlns:tal="http://xml.zope.org/namespaces/tal"
          xmlns:metal="http://xml.zope.org/namespaces/metal"
      >Dear <tal:x replace="options/mto"/>,
 
      <tal:x replace="user/getId"/> would like to thank you for 
      your interest in:
      <tal:x replace="root/absolute_url"/>
 
      <tal:x replace="options/message"/>
 
      cheers,

      The Web Team
      </tal:body> 

      Now add a Script (Python) in the same folder containing the
      following: 

      container.my_mt(
          mfrom='webmaster@example.com',
          mto='user@example.com',
          subject='This is a test!',
          message='This is a test!'
      )

      return 'Mail Sent!'

      ..and now hit the Test tab of the Script (Python)!

    File System Directory View Example

      This example sends a simple templated mail to all the members of
      a CMF portal. Please make sure your portal has at least one
      member before you try this or you won't get any output!

      Add a file called my_mt.mt to a filesystem directory that is
      mapped though to an FSDV containing the following:

      <tal:body xmlns:tal="http://xml.zope.org/namespaces/tal"
          xmlns:metal="http://xml.zope.org/namespaces/metal"
      >Dear <tal:x replace="options/member/getUserName"/>,
     
      Thankyou for you interest in our portal!

      cheers,

      The Web Team
      </tal:body>
   
      Now add a file called my_mt.mt.metadata in the same directory
      containing the following:

      [default]
      mailhost=MailHost
      mfrom=webmaster@example.com
      subject=Thankyou for your interest!

      Finally, add a file alled send_mails.py in the same directory
      containing the following:

      for member in context.portal_membership.listMembers():
        context.my_mt(
          member=member,
          mto=member.getProperty('email')
          )

      Then, to test, visit your equivalent of the following while
      logged in as a Manager:

      http://localhost:8080/myportal/send_mails

    Attachment Example
  
      This example sends a simple templated mail with a file attached
      to it to a specific address.

      Add a Mail Template called my_mt and containing the following:

      <tal:body xmlns:tal="http://xml.zope.org/namespaces/tal"
          xmlns:metal="http://xml.zope.org/namespaces/metal"
      >Dear <tal:x replace="options/mto"/>,
 
      Please find attached the file you requested.
 
      cheers,

      The Web Team
      </tal:body>

      Now add a Zope File object containing the file of your choice
      but called 'myfile.bin'.

      Finally add a Script (Python) called send_mail containing the
      following:

      msg = container.my_mt.as_message(
            mfrom='from@example.com',
            mto='to1@example.com',
            subject='Your requested file',
            )
      msg.add_file(container['myfile.bin'])
      msg.send()
      return 'Mail Sent!'

      When you tests this Script (Python), the two addresses in the
      mto parameter will receive a multi-part MIME-encoded email with
      your file attached.

    Dynamic Subject Line Example

      This example shows how to use a templated subject line.

      Add the following to a Mail Template called my_mt:

      <tal:body xmlns:tal="http://xml.zope.org/namespaces/tal"
          xmlns:metal="http://xml.zope.org/namespaces/metal"
      >Dear <tal:x replace="options/mto"/>,
 
      Welcome to our site!
 
      cheers,

      The Web Team
      </tal:body>

      Add a string property called 'subject' containing
      'Welcome to %s', and a string property called 'mfrom' containing
      'webmaster@example.com', to the my_mt Mail Template.

      Now add a Script (Python) in the same folder containing the
      following: 

      container.my_mt(
          mto='user@example.com',
          subject=container.my_mt.subject % container.absolute_url()
      )

      return 'Mail Sent!'

      ..and now hit the Test tab of the Script (Python)!

  Licensing

     Copyright (c) 2005-2006 Simplistix Ltd

     This Software is released under the MIT License:
     http://www.opensource.org/licenses/mit-license.html
     See license.txt for more details.

  Changes

     1.1.1

       - Fixed bug that meant rendering a MailTemplate or
         FSMailTemplate would set the content type of the RESPONSE to
         that of the MailTemplate.

       - Fixed a deprecation warning with Zope 2.9 at the expense of
         compatability with Zope 2.7 or less.

     1.1.0 

       - Corrected and wrote tests for the examples in readme.txt.
         (https://secure.simplistix.co.uk/support/issue185)
         Thanks to Nicolas Georgakopoulos for testing these!

       - Fixed the security declaration for BaseMailTemplate's _send
         method. 
         Thanks to Jens Quade for the patch!

       - Fixed a critical bug in MTMultipart's security declarations
         that prevented add_file from being used within python
         scripts.
         (https://secure.simplistix.co.uk/support/issue184)
         Thanks to Nicolas Georgakopoulos for reporting this!

       - Fixed a bug where specifying content_type in a .metadata
         accompanying an FSMailTemplate caused errors if you tried to
         customise that FSMailTemplate.

       - Check that the mail host specified is really a mail host and
         give feedback on the edit screen if this isn't the case.
         (https://secure.simplistix.co.uk/support/issue181)
         Thanks to Nicolas Georgakopoulos for reporting this!

       - Added support to the add_file method so that files can be
         added using a string of data and a string containing the
         filename.

       - Added the ability to explicitly set the content type when
         calling add_file.

       - Fixed the tests to run in Zope 2.8, CMF 1.5 and 
         Zope 2.6, CMF 1.4. 

       - Implemented _readFile in FSMailTemplate. This is primarily to
         work around a bug in CMF 1.4, but also means _readFile is
         much simpler for FSMailTemplates and there won't be suprises later.

     1.0.0

       - Added encoding support and documentation explaining how
         unicode and encoded string data must be handled.

       - A date header is now set on all emails sent.
 
       - An exception is now raised if certain required parameters
         cannot be looked up anywhere.

       - Made header lookup with respect to sourcing from parameter,
         properties and the headers parameter/property work as
         expected.

       - Added documentation.

       - as_message now returns an object that has both a 'send'
         method and an 'add_file' method.

       - Security declarations to allow the use of the whole email
         package from restricted code.

       - Corrected copyright statements.

       - Add support for MaildropHost   

       - give friendlier error messages when no MailHost is specified
         or where the specified one can no longer be found.

       - Prevent \r showing up in rendered mails

       - Make tests run on both unix and windows.

       - Added new icons       

     0.8.0

       - Initial release

