The TurboMail Guide (Draft)

Introduction

TurboMail is a multi-threaded mail delivery subsystem and MIME message generation framework for Python. Beginning life as a fully-integrated extension to TurboGears, a web application framework, TurboMail has been updated in version 3 to allow its use in any Python application, any framework.

TurboMail offers:

• Simplified creation of complex messages, including rich text, attachments, and more.

• Modular delivery managers including the blocking immediate manager, or the two threading managers: on-demand, and polling.

• Modular back-ends including SMTP, Sendmail, or on-disk.

• Easier debugging when using the debug back-end in concert with the immediate manager.

• A plugin architecture.

• GUID message IDs for message tracking, identification, and logging.

• S/MIME encryption and digital signatures.

• Automatic integration into TurboGears 1.x.

Python includes several standard packages for handling e-mail. These libraries are independent of each-other, their documentation is hard-to-follow, and their examples are hardly real-world. TurboMail ties these dispersant elements together with an elegant and extensible API, freeing you (the developer) from drudge-work, strained eyes, and loss of hair, even for the most complicated use-cases.

Compatibility & Requirements

TurboMail is compatible with Python 2.3, 2.4, and 2.5, and requires setuptools and the uuid module if not running within Python 2.5. For S/MIME digital signatures and encryption TurboMail requires M2Crypto.

Installation & Upgrade

With setuptools, installation is as easy as running the following command:

easy_install -U TurboMail

(Only include -U if upgrading an existing installation.)

Similarly, if you want SMIME support, run the following instead:

easy_install -U TurboMail[smime]

TurboMail installs no external scripts.

Development

The latest revision for the development version can be checked out with the following command:

svn co http://www.python-turbomail.org/svn/trunk TurboMail-3.0dev

Configuring TurboMail

Before you can use TurboMail, you must enable a few options. If you are using TurboMail as a standalone package inside your application, you configure options directly. Update the config property of the interface object with your configuration before telling TurboMail to start:

from turbomail.control import interface

interface.config.update({
        'mail.on': True,
        # ...
    })

interface.start()

If you are using a supported framework (like TurboGears), you should define these configuration directives in your application's production, debugging, or application-wide configuration files. The framework will also manage starting and stopping TurboMail for you.

Basic Directives

mail.on — Defaults to False.

Enable TurboMail for this application. If this is unset (or False), TurboMail will not start up when requested and attempts to deliver mail will raise a MailNotEnabledError exception. You can, however, still use the MIME Message generation class.

mail.manager — Defaults to "immediate".

The delivery manager to use. There are generally two types of managers: threaded and blocking. Threaded managers maintain a queue and immediately return control to the calling application after a message has been enqueued. A blocking manager will block your program flow until it knows if the message has been delivered, one way or the other.

mail.provider — Defaults to "debug".

The delivery provider to use. Delivery providers interface TurboMail with an appropriate delivery mechanism, like SMTP, Sendmail, or on-disk queues.

mail.encoding — Defaults to "us-ascii".

Which encoding should be used to encode headers and message content.

mail.tries — Defaults to 3.

How many times should message delivery be attempted, per message, before TurboMail gives up? This causes recursion for blocking managers and re-enqueueing for threaded ones.

mail.%s.on — Defaults to False.

Enable the named extension, where %s is replaced with the plug-in name, from setuptools. For example, this is used to enable the UTF-8 Quoted Printable and delivery tracking/notification modules:

mail.utf8qp.on = True
mail.notification.on = True

Extensions

Extensions may provide their own configuration directives. Please refer to the extension's documentation for more information.

Messages

These options allow you to specify defaults to be used when instantiating new Message objects. These are useful to default the sender, reply-to, bcc, and other information in an application-wide configuration.

For details on what each option represents, please see the Message class documentation further along in this guide.

Address Lists

mail.message.author

mail.message.sender

mail.message.reply

mail.message.cc

mail.message.bcc

mail.message.disposition

These can be represented as a single string, a 2-tuple of (name, address) strings, a list of strings or 2-tuples, or as Address or AddressList objects. For example:

mail.message.author = ('Application Name', 'application@example.com')
mail.message.reply = ('Responsible Party', 'notme@example.com')

Others

mail.message.organization

mail.message.priority

See the Message class documentation.

mail.message.headers

Represented as a list of 2-tuples in the form (name, value). Encoding is handled automatically.

Delivery Managers

Delivery managers provide an interface between you and an underlying delivery provider. This allows error handling, threading, and queue management to be implemented at a high level, ignorant of the mechanisms behind low-level delivery providers. This is a Good Thing™ as it allows complex management features to be added easily.

There are several managers that come pre-packaged with TurboMail:

Immediate Delivery Manager

Deliver messages immediately and pass along any exceptions to the calling application.

On-Demand Delivery Manager

Deliver messages in the background with immediate thread creation.

Polling Delivery Manager

Deliver messages in the background with regularly timed thread creation.

Delivery Providers

Providers are the interface between delivery managers and some method for actually delivering messages. Unfortunately, many of these delivery methods are deferred and so there is no immediate and guaranteed way to determine if message delivery was successful or not. Such is the way of the asynchronous internet and mail services that lie.

There are a handful of providers included with TurboMail. These include:

Debugging Delivery Provider

Pretend to deliver messages, never become exhausted, and log the entire message contents to the delivery log.

Disk Delivery Provider?

Write message bodies to files on disk.

Sendmail Delivery Provider?

Deliver messages using a locally installed sendmail-compliant application.

Mail Sink Provider?

Pretend to deliver messages while storing them in-memory for later retrieval.

SMTP Delivery Provider

Deliver messages through a server using the SMTP protocol.

Usage

For information on the usage of the Message class, please see the Message class wiki page?.

Standalone

You can get the general idea behind TurboMail from the following example code. This code will successfully run with only minor modifications to the configuration.

from turbomail.message import Message
from turbomail.control import interface

# Configure TurboMail to connect to an open SMTP relay.
interface.config.update({
        'mail.on': True,
        'mail.provider': 'smtp',
        'mail.smtp.server': 'smtp.example.com'
    })

# Initalize TurboMail and its various extensions.
interface.start()

# Create a message to deliver.
message = Message(
        author = "webmaster@example.com",
        to = "user@example.com",
        subject = "Hello from TurboMail 3.0!",
        plain = "This is a sample message from TurboMail."
    )

# Deliver the message.
interface.send(message)

# Give TurboMail a chance to shut down.
interface.stop()

TurboGears

Usage in TurboGears is identical to standalone usage, save that the configuration is done within your application's configuration files and that TurboGears automatically starts and stops TurboMail with your application.

API Reference

There are many additional options which are best described in the source or API reference guides. The API reference guide can be generated using Epydoc and the included configuration file. Use the following command to generate the documentation:

epydoc --config=epydoc.cfg

Documentation will be generated (along with a few harmless errors because TurboMail is not running within TurboGears) inside the documentation/api folder of the source tree. No documentation will be installed if you use easy_install or a binary package—it is included with the source only.

Footnotes

This work is licensed under a Creative Commons Attribution-Share Alike 2.5 Canada License.