~launchpad-pqm/launchpad/devel

Launchpad and Email

===================

Quickstart

----------

Create the file override-includes/+mail-configure.zcml with contents

similar to the following::

    <configure

        xmlns="http://namespaces.zope.org/zope"

        xmlns:mail="http://namespaces.zope.org/mail"

        i18n_domain="zope">

        <!-- delete the username and password attributes if you don't use

            SMTP auth -->

        <mail:smtpMailer

            name="smtp"

            hostname="localhost"

            port="25"

            username="biggus"

            password="dickus"

            />

        <mail:stubMailer

            name="stub"

            from_addr="stuart@stuartbishop.net"

            to_addr="stuart@stuartbishop.net"

            mailer="smtp"

            rewrite="false"

            />

        <mail:testMailer name="test-mailer" />

        <mail:mboxMailer

            name="mbox"

            filename="/tmp/launchpad.mbox"

            overwrite="true"

            mailer="test-mailer"

            />

    <!--

        Uncomment me if you want to get copies of emails in your normal inbox,

        via the stubMailer above.  However, tests will fail because they

        depend on using a directDelivery mailer.  See below.

        <mail:queuedDelivery

            mailer="stub"

            permission="zope.SendMail"

            queuePath="/var/tmp/launchpad_mailqueue" />

    -->

    <!--

        Uncomment me if you want to get test emails in a Unix mbox file, via

        the mboxMailer above.

        <mail:directDelivery

            mailer="mbox"

            permission="zope.SendMail"

            />

    -->

    </configure>

Options

-------

Zope3 provides two defined mailers out of the box (`smtp` and `sendmail`) so

most people won't actually need the `mail:smtpMailer` tag because the defaults

will usually just work.  However, several additional mailers are available for

you to use, depending on what you're trying to do.

The `mail:stubMailer` can be used to forward all emails to your normal inbox

via some other mailer.  Think of it as a proxy mailer that can be used to

specify explicit MAIL FROM and RCTP TO envelope addresses.  The `rewrite`

attribute of the `mail:stubMailer` specifies whether the RFC 2822 headers

should also be rewritten.  You and your spam filters might prefer this set to

`true`.

The `mail:mboxMailer` stores messages in a Unix mbox file and then forwards

the message on to another mailer.  You can use this if you want a record on

disk of all the messages sent, or if you'd rather not clutter up your inbox

with all your Launchpad test email.  The `overwrite` attribute says whether to

truncate the mbox file when Launchpad starts up (i.e. opens the file once in

'w' mode before appending all new messages to the file).

The `mail:testMailer` is necessary for the Launchpad tests to work.  You must

use a `mail:directDelivery` mailer for the tests, otherwise you'll get lots of

failures.  Basically, the testMailer stores the messages in a list in memory.

For both `mail:mboxMailer` and `mail:stubMailer` the `mailer` attribute

specifies the next mailer in the chain that the message will get sent to.

Thus if `mailer` is set to `smtp`, you'll get the messages in your inbox, but

if it's `test-mailer`, the unit tests will work.

Finally, these are all hooked up at the top with either a

`mail:queuedDelivery` section or a `mail:directDelivery` tag.  You must

use a `mail:directDelivery` tag if you want the unit tests to work because

otherwise, the in-memory list of the `mail:testMailer` won't be updated by the

time the unit test checks it.

If you just want the unit tests to work normally, don't include a

`mail:queuedDelivery` or a `mail:directDelivery` section at all.  Launchpad

will DTRT internally.  However, if you want copies in an mbox file or in your

inbox, set the `mailer` attribute to the appropriate mailer, chaining that to

a `mail:testMailer` for the unit tests or a `mail:smtpMailer` for

development.

API

---

Launchpad code should use the methods defined in canonical.launchpad.mail

to send emails (`simple_sendmail`, `sendmail` or possibly `raw_sendmail`)

Functional Tests

----------------

The functional test harness is configured to allow easy testing of

emails.  See `canonical/launchpad/mail/ftests/test_stub.py` for example

code.

Details

-------

To send email from Zope3, you use an `IMailDelivery` Utility, which

defines a single `send` method. There are two standard `IMailDelivery`

implementations:

    1. `QueuedDelivery` -- email is delivered in a seperate thread. We use

        this for production.

    2. `DirectDelivery` -- email is send synchronously during transaction

        commit.  We use this for tests.

Both implementations will send no email if the transaction is aborted.  Both

implementations use events to notify anything that cares to subscribe if

delivery succeeded or failed.  Both implementations look up an `IMailer`

utility by name to do the actual delivery, as specified in the `mailer`

attribute of the `queuedDelivery` and `directDelivery` ZCML tags.

Zope3 provides two `IMailer` implementations out of the box:

    1. `SMTPMailer` -- sends email using SMTP

    2. `SendmailMailer1 -- Uses the `sendmail` program to send email.

In addition to these two, there are three more `IMailer` implementations

for use with Launchpad development (production instances will just use

`SMTPMailer` or `SendmailMailer`):

    3. StubMailer -- rewrites the envelope headers and optionally the RFC 2822

       To and From headers before handing on to a different `IMailer`.

    4. TestMailer -- stores the email in memory in a Python list object called

       `canonical.launchpad.mail.stub.test_email` for easy access by unit

       tests.

    5. MboxMailer -- stores the email in a Unix mbox file before optionally

       handing the message off to another `IMailer`.

Developers (and production and dogfood server, until we are confident

messaging is working fine) should use the StubMailer, like in the quickstart

example.  This causes all emails to be redirected to the specified destination

address to you can test to your hearts content without spamming other

developers or innocent civilians.  Or you can use the MboxMailer.

The functional test suite is already configured to use the TestMailer.

However, if you use a StubMailer or MboxMailer and want the test suite to

work, you must hook it up to a TestMailer explicitly.  See

`canonical/launchpad/mail/ftests/test_stub.py` for an example showing how

functional tests can check that notifications are being sent correctly.