1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
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.
|