repoze.sendmailRepoze Sendmail===============
repoze.sendmail
===============
`repoze.sendmail` allows coupling the sending of email messages with a
transaction, using the Zope transaction manager. This allows messages to
only be sent out when and if a transaction is committed, preventing users
from receiving notifications about events which may not have completed
successfully. Messages may be sent directly or stored in a queue for later
sending. The queued mail approach is the more common and recommended path. A
console application which can flush the queue, sending the messages that it
finds, is included for convenience.
`repoze.sendmail` is a fork of `zope.sendmail`. Functionality that was
specific to running in a Zope context has been removed, making this version
more generally useful to users of other frameworks.
Note that repoze.sendmail works only under Python 2.5+ (it will not work
under 2.4) and Python 3.2+. Note that the ``transaction`` package, which
this package depends on, must be less than 1.2 to work under Python 2.5 (1.2
is 2.6-and-better).
==============
Basic Tutorial
==============
Messages are sent by means of a `Delivery` object. Two deliveries are included
in `repoze.sendmail.delivery`: `QueuedMailDelivery` and `DirectMailDelivery`.
A delivery implements the interface defined by
`repoze.sendmail.interfaces.IDelivery`, which consists of a single `send`
method::
def send(fromaddr, toaddrs, message):
""" Sends message on transaction commit. """
`fromaddr` is the address of the sender of the message. `toaddrs` is a list of
email addresses for recipients of the message. `message` must be an instance
`email.message.Message` and is the actual message which will be sent.
To create a queued delivery::
from email.message import Message
from repoze.sendmail.delivery import QueuedMailDelivery
message = Message()
message['From'] = 'Chris <chris@example.com>'
message['To'] = 'Paul <paul@example.com>, Tres <tres@example.com>'
message['Subject'] = "repoze.sendmail is a useful package"
message.set_payload("The subject line says it all.")
delivery = QueuedMailDelivery('path/to/queue')
delivery.send('chris@example.com', ['paul@example.com', 'tres@example.com'],
message)
The message will be added to the maildir queue in 'path/to/queue' when and if
the current transaction is committed successsfully.
`repoze.sendmail` includes a console app utility for sending queued messages::
$ bin/qp path/to/queue
This will attempt to use an SMTP server at localhost to send any messages found
in the queue. To see all options available::
$ bin/qp --help
Direct delivery can also be used::
from repoze.sendmail.delivery import DirectMailDelivery
from repoze.sendmail.mailer import SMTPMailer
mailer = SMTPMailer() # Uses localhost, port 25 be default.
delivery = DirectMailDelivery(mailer)
delivery.send('chris@example.com', ['paul@example.com', 'tres@example.com'],
message)
repoze.sendmail hooks into the Zope transaction manager and only sends
messages on transaction commit. If you are using a framework which, like
`repoze.bfg`, does not use transactions by default, you will need to begin and
commit a transaction of your own in order for mail to be sent::
import transaction
transaction.manager.begin()
try:
my_code_here()
transaction.manager.commit()
except e:
transaction.manager.abort()
raise e
Change history
~~~~~~~~~~~~~~
4.0b1 (2013-01-09)
------------------
- Dropped support for Jython until a Jython-2.7-compatible version of
``zope.interface`` becomes available.
- Dropped support for Python 2.5.
- Added suupport for Python 3.3.
- Improved test for SSL feature under Python 3.x.
- Added new tests for proper encoding of binary attachments.
- Cauterized resource leak warnings under Python 3.2.
3.2 (2012-05-03)
----------------
- Issue #7: fixed handling of to/from addresses with non-ascii
characters when using queued mail delivery.
- Suppressed duplicate usage message output from ``qp``.
3.1 (2012-03-26)
----------------
- Fixed ``qp`` queue processor mail delivery under Python 3.0.
- Added 'setup.py dev' alias (runs ``setup.py develop`` plus installs
``nose`` and ``coverage``).
3.0 (2012-03-20)
----------------
- Fixed `Message-Id` handling (see http://bugs.repoze.org/issue177).
- Provided improved support for encoding messages to bytes. It should now be
possible to represent your messages in `email.message.Message` objects just
with unicode (excepting bytes for binary attachments) and the mailer will
handler it as appropriate.
- Added tests for cPython 2.5, 2.6, 2.7, 3.2, jython 2.5 and pypy 1.8
compatibility.
2.3 (2011-05-17)
----------------
- Queued delivery now creates a copy of the passed in messsage before adding
the 'X-Actually-{To,From}' headers. This avoids rudely mutating the message
being sent in ways that might not be expected by the sender. (LP #780000)
2.2 (2010-09-14)
----------------
- Made debug output for SMTP mailer optional. (Thanks to Igor Stroh for
patch.)
2.1 (2010-07-28)
----------------
- Silently ignore redundant calls to abort transaction. (LP #580164)
2.0 (2010-03-10)
----------------
Represents major refactoring with a number of backwards incompatible changes.
The focus of the changes is on simplifying and updating the internals,
removing usage of deprecated APIs, removing unused functionality and using the
`email` module from the standard library wherever possible. A few changes have
been made solely to reduce internal complexity.
- Public facing APIs no longer accept messages passed as strings. Messages
must be instances of email.message.Message.
- Deprecated APIs have been replaced with newer 'email' module throughout.
- Functions that return message ids no longer strip containing less than and
greater than characters.
- Events were removed entirely. There was nothing in the code actually
performing a notify anyway. Removes dependency on zope.event.
- Normalized directory structure. (Got rid of 'src' directory.)
- Got rid of functions to send queued mail from a thread or a daemon process.
These are more appropriately handled in the calling code.
- Removed vocabulary. It was a fossil from its days as zope.sendmail and was
not used by anything.
- Got rid of the zcml directives. These were written in such a way that you
would end up putting deployment configuration in your zcml, which is a
fundamentally broken pattern. Users of the ZCA may still register utilities
aginst the IMailDelivery and IMailer interfaces. This is the recommended way
to use repoze.sendmail with the Zope Component Architecture.
- Removed all interfaces that did not correspond to a rational plug point.
This leaves only IMailDelivery and IMailer.
- Removed dependency on zope.i18nmessageid
- No longer works under Python 2.4 (Python 2.5 required).
1.2 (2010-02-11)
----------------
- Maildir storage for queue can now handle unicode passed in for message or
to/from addresses.
1.1 (2009-02-24)
----------------
- Added logging to queue processor console app.
- Added ini config parsing to queue processor console app.
1.0 (2009-02-24)
----------------
- Initial release
- Copy of zope.sendmail with dependency on security removed.Chris Rossi077af4d52387f179a077d47e9bb8c9583a170f6a4.0b1