Navigation

pyramid_mailer is a package for the Pyramid framework to take the pain
out of sending emails. It is compatible with Python 2.5, 2.6, 2.7, and
3.2. It has the following features:

A wrapper around the low-level email functionality of standard
Python. This includes handling multipart emails with both text and HTML
content, and file attachments.

The option of directly sending an email or adding it to the queue in your
maildir.

Wrapping email sending in the transaction manager. If you have a view that
sends a customer an email for example, and there is an error in that view
(for example, a database error) then this ensures that the email is not
sent.

A pyramid_mailer.DummyMailer class to help with writing unit
tests, or other situations where you want to avoid emails being sent
accidentally from a non-production install.

pyramid_mailer uses the repoze_sendmail package for general email
sending, queuing and transaction management, and it borrows code from Zed
Shaw’s Lamson library for low-level multipart message encoding and
wrapping.

Include the pyramid_mailer.debug module in your application’s
configuration (see Debugging) so mails save to a local file.

Run a fake SMTPD server for developing and debugging your webapp. Python
provides an SMTP server in its standard library called smptd. We can make
use of it by simply running the following command in a new terminal (this
example uses port 2525; feel free to change that):

python -m smtpd -n -c DebuggingServer localhost:2525

Use your ISP’s mail relay.

Ensure an SMTP server is installed and running. This is usually used
for a production environment. Follow instructions for the appropriate operating
system:

The Message is then passed to the Mailer instance. You can either
send the message right away:

mailer.send(message)

or add it to your mail queue (a maildir on disk):

mailer.send_to_queue(message)

Usually you provide the sender to your Message instance. Often
however a site might just use a single from address. If that is the case you
can provide the default_sender to your Mailer and this will be used
in throughout your application as the default if the sender is not
otherwise provided.

If you don’t want to use transactions, you can side-step them by using
send_immediately():

mailer.send_immediately(message,fail_silently=False)

This will send the email immediately, without the transaction, so if it fails
you have to deal with it manually. The fail_silently flag will swallow
any connection errors silently - if it’s not important whether the email gets
sent.

The mailer can take a number of optional settings, detailed in
Configuration. It’s a good idea to create a single Mailer instance
for your application, and add it to your registry in your configuration
setup:

2.6 or higher, as it uses the SSL additions to the smtplib
package. While it may be possible to work around this if you have to use
Python 2.5 or lower, pyramid_mailer does not support this out of the
box.

Note: the mail.debug option will be passed to the underlying
smtplib connection. Any values for this option that Python would consider
>0 will result in debug messages for all messages sent and received from
the server. Thus, specifying mail.debug with any value will result in debug
messages as pyramid_mailer will not attempt to coerce this value from its
original string.

When the repoze.tm2tm
middleware is in your Pyramid WSGI pipeline or if you’ve included the
pyramid_tm package in your Pyramid configuration, transactions are
already managed for you, so you don’t need to explicitly commit or abort
within code that sends mail. Instead, if an exception is raised, the
transaction will implicitly be aborted and mail will not be sent; otherwise
it will be committed, and mail will be sent.

If your site is in development and you want to avoid accidental sending of any
emails to customers, but still see what emails would get sent, you can use
config.include('pyramid_mailer.debug') to make the current mailer an
instance of the pyramid_mailer.mailer.DebugMailer, hence writing all
emails to a file instead of sending them out. In other words if you add
pyramid_mailer.debug to your development.ini, all emails that would be sent
out will instead get written to files so you can inspect them:

When you send mail to a queue via
pyramid_mailer.mailer.Mailer.send_to_queue(), the mail will be placed
into a maildir directory specified by the queue_path parameter or
setting to
pyramid_mailer.mailer.Mailer. A separate process will need to be
launched to monitor this maildir and take actions based on its state. Such a
program comes as part of repoze_sendmail (a dependency of the
pyramid_mailer package). It is known as qp. qp will be
installed into your Python (or virtualenv) bin or Scripts directory
when you install repoze_sendmail.

qp is a script that is meant to be run as a cron job because what it does
is that it looks at maildir and sends messages. You’ll need to arrange
for qp to be a long-running process that monitors the maildir state.:

$ bin/qp /path/to/mail/queue

This will attempt to use the localhost SMTP server to send any messages in
the queue over time. qp has other options that allow you to choose
different settings. Use it’s --help parameter to see more:

$ bin/qp --help

Note

Sending messages via the queue requires the use of a transaction manager.
If no manager is enabled, it must be emulated by issuing a manual commit
via transaction.commit().

disposition – content-disposition (if any, may contain extra
params in the form ‘attachment; filename=”fred.txt”’). If filename
is supplied in the disposition, it will be used if no filename
is supplied to the Attachment constructor. If disposition is
not supplied, it will default to ‘attachment’.

transfer_encoding – content-transfer-encoding (if any, may be
‘base64’ or ‘quoted-printable’). If it is not supplied, it will
default to ‘base64’.