~launchpad-pqm/launchpad/devel

1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
1
Launchpad and Email
2
===================
3
13932.1.5 by mbp at canonical
Document process-one-mail.
4
Quicker interactive testing
5
---------------------------
6
7
There is a script ``process-one-mail.py`` which reads a single mail
8
message from a file (or stdin), processes it as if it had been received by
13932.1.7 by mbp at canonical
Review tweaks and documentation
9
Launchpad, and then prints out any mail generated in response.  For
13932.1.5 by mbp at canonical
Document process-one-mail.
10
quasi-interactive testing of email processing this may be your best bet.
11
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
12
Quickstart
13
----------
14
13932.1.5 by mbp at canonical
Document process-one-mail.
15
Otherwise, you can configure Launchpad with an incoming mailbox and an
16
outgoing mailer, in a way somewhat similar to what is used in production.
17
This lets you catch mail sent other than in response to an incoming
18
message.
19
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
20
Create the file override-includes/+mail-configure.zcml with contents
21
similar to the following::
22
23
    <configure
24
        xmlns="http://namespaces.zope.org/zope"
25
        xmlns:mail="http://namespaces.zope.org/mail"
26
        i18n_domain="zope">
27
28
        <!-- delete the username and password attributes if you don't use
29
            SMTP auth -->
30
        <mail:smtpMailer
31
            name="smtp"
32
            hostname="localhost"
33
            port="25"
34
            username="biggus"
35
            password="dickus"
36
            />
37
38
        <mail:stubMailer
39
            name="stub"
40
            from_addr="stuart@stuartbishop.net"
41
            to_addr="stuart@stuartbishop.net"
42
            mailer="smtp"
43
            rewrite="false"
44
            />
45
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
46
        <mail:testMailer name="test-mailer" />
47
48
        <mail:mboxMailer
49
            name="mbox"
50
            filename="/tmp/launchpad.mbox"
51
            overwrite="true"
52
            mailer="test-mailer"
53
            />
54
55
    <!--
56
57
        Uncomment me if you want to get copies of emails in your normal inbox,
58
        via the stubMailer above.  However, tests will fail because they
59
        depend on using a directDelivery mailer.  See below.
60
61
        <mail:queuedDelivery
62
            mailer="stub"
63
            permission="zope.SendMail"
64
            queuePath="/var/tmp/launchpad_mailqueue" />
65
66
    -->
67
    <!--
68
69
        Uncomment me if you want to get test emails in a Unix mbox file, via
70
        the mboxMailer above.
71
72
        <mail:directDelivery
73
            mailer="mbox"
74
            permission="zope.SendMail"
75
            />
76
    -->
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
77
78
    </configure>
79
80
81
Options
82
-------
83
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
84
Zope3 provides two defined mailers out of the box (`smtp` and `sendmail`) so
85
most people won't actually need the `mail:smtpMailer` tag because the defaults
86
will usually just work.  However, several additional mailers are available for
87
you to use, depending on what you're trying to do.
88
89
The `mail:stubMailer` can be used to forward all emails to your normal inbox
90
via some other mailer.  Think of it as a proxy mailer that can be used to
91
specify explicit MAIL FROM and RCTP TO envelope addresses.  The `rewrite`
92
attribute of the `mail:stubMailer` specifies whether the RFC 2822 headers
93
should also be rewritten.  You and your spam filters might prefer this set to
94
`true`.
95
96
The `mail:mboxMailer` stores messages in a Unix mbox file and then forwards
97
the message on to another mailer.  You can use this if you want a record on
98
disk of all the messages sent, or if you'd rather not clutter up your inbox
99
with all your Launchpad test email.  The `overwrite` attribute says whether to
100
truncate the mbox file when Launchpad starts up (i.e. opens the file once in
101
'w' mode before appending all new messages to the file).
102
103
The `mail:testMailer` is necessary for the Launchpad tests to work.  You must
104
use a `mail:directDelivery` mailer for the tests, otherwise you'll get lots of
105
failures.  Basically, the testMailer stores the messages in a list in memory.
106
107
For both `mail:mboxMailer` and `mail:stubMailer` the `mailer` attribute
108
specifies the next mailer in the chain that the message will get sent to.
109
Thus if `mailer` is set to `smtp`, you'll get the messages in your inbox, but
110
if it's `test-mailer`, the unit tests will work.
111
112
Finally, these are all hooked up at the top with either a
113
`mail:queuedDelivery` section or a `mail:directDelivery` tag.  You must
114
use a `mail:directDelivery` tag if you want the unit tests to work because
115
otherwise, the in-memory list of the `mail:testMailer` won't be updated by the
116
time the unit test checks it.
117
118
If you just want the unit tests to work normally, don't include a
119
`mail:queuedDelivery` or a `mail:directDelivery` section at all.  Launchpad
120
will DTRT internally.  However, if you want copies in an mbox file or in your
121
inbox, set the `mailer` attribute to the appropriate mailer, chaining that to
122
a `mail:testMailer` for the unit tests or a `mail:smtpMailer` for
123
development.
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
124
125
126
API
127
---
128
13668.1.23 by Curtis Hovey
Fixed imports that relied on globs.
129
Launchpad code should use the methods defined in lp.services.mail.sendmail
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
130
to send emails (`simple_sendmail`, `sendmail` or possibly `raw_sendmail`)
131
132
133
Functional Tests
134
----------------
135
13697.10.1 by Gavin Panella
Update mailer documentation.
136
The functional test harness is configured to allow easy testing of emails.
137
See `lp/services/mail/tests/test_stub.py` for example code.
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
138
139
140
Details
141
-------
142
143
To send email from Zope3, you use an `IMailDelivery` Utility, which
144
defines a single `send` method. There are two standard `IMailDelivery`
145
implementations:
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
146
14645.1.1 by Colin Watson
Fix a slew of typos that have been annoying me.
147
    1. `QueuedDelivery` -- email is delivered in a separate thread. We use
13697.10.1 by Gavin Panella
Update mailer documentation.
148
       this for production.
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
149
150
    2. `DirectDelivery` -- email is send synchronously during transaction
13697.10.1 by Gavin Panella
Update mailer documentation.
151
       commit.  We use this for tests.
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
152
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
153
Both implementations will send no email if the transaction is aborted.  Both
154
implementations use events to notify anything that cares to subscribe if
155
delivery succeeded or failed.  Both implementations look up an `IMailer`
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
156
utility by name to do the actual delivery, as specified in the `mailer`
157
attribute of the `queuedDelivery` and `directDelivery` ZCML tags.
158
159
Zope3 provides two `IMailer` implementations out of the box:
160
161
    1. `SMTPMailer` -- sends email using SMTP
162
163
    2. `SendmailMailer1 -- Uses the `sendmail` program to send email.
164
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
165
In addition to these two, there are three more `IMailer` implementations
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
166
for use with Launchpad development (production instances will just use
167
`SMTPMailer` or `SendmailMailer`):
168
13697.10.1 by Gavin Panella
Update mailer documentation.
169
    3. `StubMailer` -- rewrites the envelope headers and optionally the RFC
170
       2822 To and From headers before handing on to a different `IMailer`.
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
171
13697.10.1 by Gavin Panella
Update mailer documentation.
172
    4. `TestMailer` -- stores the email in memory in a Python list object
173
       called `lp.services.mail.stub.test_email` for easy access by unit
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
174
       tests.
175
13697.10.1 by Gavin Panella
Update mailer documentation.
176
    5. `MboxMailer` -- stores the email in a Unix mbox file before optionally
3935.2.8 by Barry Warsaw
Address spiv's review comments.
177
       handing the message off to another `IMailer`.
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
178
3691.394.1 by Barry Warsaw
Trivial documentation fixes.
179
Developers (and production and dogfood server, until we are confident
180
messaging is working fine) should use the StubMailer, like in the quickstart
181
example.  This causes all emails to be redirected to the specified destination
182
address to you can test to your hearts content without spamming other
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
183
developers or innocent civilians.  Or you can use the MboxMailer.
1102 by Canonical.com Patch Queue Manager
Lucille had some XXXs which should have been NOTEs
184
185
The functional test suite is already configured to use the TestMailer.
3935.2.2 by Barry Warsaw
Added `mailer` attribute to `mail:mboxMailer` directive so that the message
186
However, if you use a StubMailer or MboxMailer and want the test suite to
187
work, you must hook it up to a TestMailer explicitly.  See
13697.10.1 by Gavin Panella
Update mailer documentation.
188
`lp/services/mail/tests/test_stub.py` for an example showing how functional
189
tests can check that notifications are being sent correctly.