===============
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 <[email protected]>'
message['To'] = 'Paul <[email protected]>, Tres <[email protected]>'
message['Subject'] = "repoze.sendmail is a useful package"
message.set_payload("The subject line says it all.")
delivery = QueuedMailDelivery('path/to/queue')
delivery.send('[email protected]', ['[email protected]', '[email protected]'],
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('[email protected]', ['[email protected]', '[email protected]'],
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