Mailer

h1(#title). Marrow Mailer

bq(subtitle). A highly efficient and modular mail delivery framework for Python 2.6+ and 3.2+, formerly called TurboMail.

bq(byline). (C) 2006-2023, Alice Bevan-McGregor and contributors.

bq(byline). "https://github.com/marrow/mailer":github-project

[github-project]https://github.com/marrow/mailer

h2(#what-is). %1.% What is Marrow Mailer?

Marrow Mailer is a Python library to ease sending emails from your application.

By using Marrow Mailer you can:

• Easily construct plain text and HTML emails.
• Improve the testability of your e-mail deliveries.
• Use different mail delivery management strategies; e.g. immediate, deferred, or even multi-server.
• Deliver e-mail through a number of alternative transports including SMTP, Amazon SES, sendmail, or even via direct on-disk mbox/maildir.
• Multiple simultaneous configurations for more targeted delivery.

Mailer supports Python 2.6+ and 3.2+ and there are only light-weight dependencies: @marrow.util@, @marrow.interface@, and @boto3@ if using Amazon SES.

h3(#goals). %1.1.% Goals

Marrow Mailer is all about making email delivery easy. Attempting to utilize the built-in MIME message generation classes can be painful, and interfacing with an SMTP server, or, worse, the command-line @sendmail@ command can make you lose your hair. Mailer handles all of these tasks for you and more.

The most common cases for mail message creation (plain text, html, attachments, and html embeds) are handled by the @marrow.mailer.message.Message@ class. Using this class allows you to write clean, succinct code within your own applications. If you want to use hand-generated MIME messages, or tackle Python's built-in MIME generation support for an advanced use-case, Mailer allows you to utilize the delivery mechanics without requiring the use of the @Message@ class.

Mailer is not an MTA like "Exim":http://www.exim.org/, "Postfix":http://www.postfix.org/, "sendmail":http://www.sendmail.com/sm/open_source/, or "qmail":http://www.qmail.org/. It is designed to deliver your messages to a real mail server ("smart host") or other back-end which then actually delivers the messages to the recipient's server. There are a number of true MTAs written in Python, however, including "Python's smtpd":http://docs.python.org/library/smtpd.html, "Twisted Mail":http://twistedmatrix.com/trac/wiki/TwistedMail, "pymta":http://www.schwarz.eu/opensource/projects/pymta/, "tmda-ofmipd":http://tmda.svn.sourceforge.net/viewvc/tmda/trunk/tmda/bin/tmda-ofmipd?revision=2194&view=markup, and "Lamson":http://lamsonproject.org/, though this is by no means an exhaustive list.

h2(#installation). %2.% Installation

Installing @marrow.mailer@ is easy, just execute the following in a terminal: [2]

<pre><code>pip install marrow.mailer</code></pre>

If you add @marrow.mailer@ to the @install_requires@ argument of the call to @setup()@ in your application's @setup.py@ file, @marrow.mailer@ will be automatically installed and made available when your own application is installed. We recommend using "less than" version numbers to ensure there are no unintentional side-effects when updating. Use @"marrow.mailer<4.1"@ to get all bugfixes for the current release, and @"marrow.mailer<5.0"@ to get bugfixes and feature updates, but ensure that large breaking changes are not installed.

Warning: The 4.0 series is the last to support Python 2.

h3(#install-dev). %2.1.% Development Version

Development takes place on "GitHub":github in the "marrow/mailer":github-project project. Issue tracking, documentation, and downloads are provided there.

Installing the current development version requires "Git":git, a distributed source code management system. If you have Git, you can run the following to download and link the development version into your Python runtime:

<pre><code>git clone https://github.com/marrow/mailer.git (cd mailer; python setup.py develop)</code></pre>

You can upgrade to the latest version at any time:

<pre><code>(cd mailer; git pull; python setup.py develop)</code></pre>

If you would like to make changes and contribute them back to the project, fork the GitHub project, make your changes, and submit a pull request. This process is beyond the scope of this documentation; for more information, see "GitHub's documentation":github-help.

[github]https://github.com/ [git]http://git-scm.com/ [github-help]http://help.github.com/

h2(#basic). %3.% Basic Usage

To use Marrow Mailer you instantiate a @marrow.mailer.Mailer@ object with the configuration, then pass @Message@ instances to the @Mailer@ instance's @send()@ method. This allows you to configure multiple delivery mechanisms and choose, within your code, how you want each message delivered. The configuration is a dictionary of dot-notation keys and their values. Each manager and transport has their own configuration keys.

Configuration keys may utilize a shared, common prefix, such as @mail.@. By default no prefix is assumed. Manager and transport configurations are each additionally prefixed with @manager.@ and @transport.@, respectively. The following is an example of how to send a message by SMTP:

<pre><code>from marrow.mailer import Mailer, Message mailer = Mailer(dict( transport = dict( use = 'smtp', host = 'localhost'))) mailer.start() message = Message(author="user@example.com", to="user-two@example.com") message.subject = "Testing Marrow Mailer" message.plain = "This is a test." mailer.send(message) mailer.stop()</code></pre>

Another example configuration, using a flat dictionary and delivering to an on-disk @maildir@ mailbox:

<pre><code>{ 'transport.use': 'maildir', 'transport.directory': 'data/maildir' }</pre></code>

h3(#mailer-methods). %3.1.% Mailer Methods

table(methods). |. Method |. Description | | @init(config, prefix=None)@ | Create and configure a new Mailer. | | @start()@ | Start the mailer. Returns the Mailer instance and can thus be chained with construction. | | @stop()@ | Stop the mailer. This cascades through to the active manager and transports. | | @send(message)@ | Deliver the given Message instance. | | @new(author=None, to=None, subject=None, **kw)@ | Create a new bound instance of Message using configured default values. |

h2(#message). %4.% The Message Class

The original format for email messages was defined in "RFC 822":http://www.faqs.org/rfcs/rfc822.html which was superseded by "RFC 2822":http://www.faqs.org/rfcs/rfc2822.html. The newest standard document about the format is currently "RFC 5322":http://www.faqs.org/rfcs/rfc2822.html. But the basics of RFC 822 still apply, so for the sake of readability we will just use "RFC 822" to refer to all these RFCs. Please read the official standard documents if this text fails to explain some aspects.

The Marrow Mailer @Message@ class has a large number of attributes and methods, described below.

h3(#message-methods). %4.1.% Message Methods

table(methods). |. Method |. Description | | @init(author=None, to=None, subject=None, **kw)@ | Create and populate a new Message. Any attribute may be set by name. | | @str@ | You can easily get the MIME encoded version of the message using the @str()@ built-in. | | @attach(name, data=None, maintype=None, subtype=None, inline=False)@ | Attach a file (data=None) or string-like. For on-disk files, mimetype will be guessed. | | @embed(name, data=None)@ | Embed an image from disk or string-like. Only embed images! | | @send()@ | If the Message instance is bound to a Mailer instance, e.g. having been created by the @Mailer.new()@ factory method, deliver the message via that instance. |

h3(#message-attributes). %4.2.% Message Attributes

h4. %4.2.1.% Read/Write Attributes

table(attributes). |. Attribute |. Description | | @_id@ | The message ID, generated for you as needed. | | @attachments@ | A list of MIME-encoded attachments. | | @author@ | The visible author of the message. This maps to the @From:@ header. | | @to@ | The visible list of primary intended recipients. | | @cc@ | A visible list of secondary intended recipients. | | @bcc@ | An invisible list of tertiary intended recipients. | | @date@ | The visible date/time of the message, defaults to @datetime.now()@ | | @embedded@ | A list of MIME-encoded embedded images. | | @encoding@ | Unicode encoding, defaults to @utf-8@. | | @headers@ | A list of additional message headers. | | @notify@ | The address that message disposition notification messages get routed to. | | @organization@ | An extended header for an organization name. | | @plain@ | Plain text message content. [1] | | @priority@ | The @X-Priority@ header. | | @reply@ | The address replies should be routed to by default; may differ from @author@. | | @retries@ | The number of times the message should be retried in the event of a non-critical failure. | | @rich@ | HTML message content. Must have plain text alternative. [1] | | @sender@ | The designated sender of the message; may differ from @author@. This is primarily utilized by SMTP delivery. | | @subject@ | The subject of the message. |

fn1. The message bodies may be callables which will be executed when the message is delivered, allowing you to easily utilize templates. Pro tip: to pass arguments to your template, while still allowing for later execution, use @functools.partial@. When using a threaded manager please be aware of thread-safe issues within your templates.

Any of these attributes can also be defined within your mailer configuration. When you wish to use default values from the configuration you must use the @Mailer.new()@ factory method. For example:

<pre><code>mail = Mailer({ 'message.author': 'Example User <user@example.com>', 'message.subject': "Test subject." }) message = mail.new() message.subject = "Test subject." message.send()</code></pre>

h4. %4.2.2.% Read-Only Attributes

table(attributes). |. Attribute |