MailTemplates 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.
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.
MailTemplates are callable objects that, when called, render the body of a mail message and either return that as an object that may have further parts added to it or actually uses a configured MailHost object to send the message.
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.
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.
The following properties can be added to a Mail Template using the Properties tab, or an accompanying .metadata file for skin-based MailTemplates:
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.
As well as influencing the ZPT engine, the property is also used as the content type for the email generated by this Mail Template.
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.
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 MailTemplate will be sent. It is also used to generate the To header.
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.
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.
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.
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.
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 rendering the template. See the section on Unicode and Encoded Strings below for more information.
The default value is that specifed in the default_zpublisher_encoding setting in zope.conf, if avaiable, or iso-8859-15 otherwise.
In addition to being directly callable, MailTemplates 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.
This method renders the email and sends it using the configured MailHost.
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.mime.text.MIMEText object, creates a MTMultipart object containing the headers for the rendered email, attaches the body to it and returns it.
In addition to the parameters described below, the following keyword parameters can also optionally be used to control aspects of the multi-part message creation:
| Parameters: |
|
|---|
The following parameter may optionally be passed as keyword arguments to both the send() and as_message() methods:
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.
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.
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.
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.
This should be a string and will be used to generate the Subject header for the mail currently being generated or sent.
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.
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 rendering non-html emails. See the section on Unicode and Encoded Strings below for more information.
The default value is that specifed in the default_zpublisher_encoding of zope.conf if avaiable, or iso-8859-15 otherwise.
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:
In order for a Mail Template to be successfully rendered, the following parameters must be obtained through one of the four options listed above:
If any of the above parameters cannot be obtained, an exception will be raised.
An MTMultipart object is identical to an email.mime.multipart.MIMEMultipart object except that is has two additional methods:
This sends a rendered version of the message described by the MTMultipart object using the MailHost configured in the MailTemplate that created it.
This method is used to add attachments to the message. It can take either one argument 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.
Please note that you can run into problems with Mail Templates in exactly the same way as for normal Page Templates.
All string-like data inserted into the Mail Template during rendering should be in the form of unicode objects or strings encoded with the same encoding specified in the MailTemplate’s parameters.
Here is a bad example to illustrate incorrect usage. While encoding is passed as a parameter here, you may find it more convenient to set as a property or by specifying the default_zpublisher_encoding in your zope.conf file.
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'£'.encode('utf-8'),
encoding='latin-1')
Should have been:
Your currency is <tal:x replace="options/currency"/>
Script (Python):
return container.test_mt(currency=u'£',
encoding='latin-1')
The following are some simple contrived examples to show some of the possible uses of MailTemplates. If you wish to test with these, you will need to change the mto addresses.
This example sends a simple templated mail to a specific address.
Add the following to a MailTemplate 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!'
Finally, hit the Test tab of the Script (Python)!
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 called 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
This example sends a simple templated mail with a file attached to it to a specific address.
Add a Mail Template called my_mt 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 test this Script (Python), the two addresses in the mto parameter will receive a multi-part MIME-encoded email with your file attached.
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 MailTemplate.
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!'
Finally, hit the Test tab of the Script (Python)!