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
Script Python:
return container.test_mt(currency=u'£'.encode('utf-8'),
encoding='utf-8')
Should have been:
Your currency is
...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
Script Python:
return container.test_mt(currency=u'£',
encoding='utf-8')
Should have been:
Your currency is
...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:
Dear ,
would like to thank you for
your interest in:
cheers,
The Web Team
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:
Dear ,
Thankyou for you interest in our portal!
cheers,
The Web Team
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:
Dear ,
Please find attached the file you requested.
cheers,
The Web Team
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:
Dear ,
Welcome to our site!
cheers,
The Web Team
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