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:queuedDelivery permission="zope.SendMail"
            queuePath="/var/tmp/launchpad_mailqueue" mailer="stub" />

    </configure>


Options
-------

Z3 provides two defined mailers out of the box (`smtp` and `sendmail`),
so most people won't actually need the `mail:smtpMailer` tag since the
defaults are fine. Just make sure that the `mailer` attribute in the
`mail:stubMailer` tag is set to either `smtp` or `sendmail`.

The `rewrite` attribute of the `mail:stubMailer` specifies if headers should
be rewritten as well as the message envelope. You and your spam filters
might prefer this set to `true`. 


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, I have implemented two more `IMailer` implementations
for use with Launchpad development (production instances will just use
`SMTPMailer` or `SendmailMailer`):

    3. StubMailer -- rewrites the message envelope and optionally
        the To and From headers before handing on to a different `IMailer`.

    4. TestMailer -- stores the email in the
        `canonical.launchpad.mail.stub.test_email` list for easy access by
        unit tests.

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. 

The functional test suite is already configured to use the TestMailer.
See `canonical/launchpad/mail/ftests/test_stub.py` for an example showing
how functional tests can check that notifications are being sent correctly.