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. |