readme.txt 19.8 KB
Newer Older
1 2
Mail Templates

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

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609
  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