bans.rst 4.83 KB
Newer Older
1
2
3
4
5
6
7
8
=======================
Banning email addresses
=======================

Email addresses can be banned from ever subscribing, either to a specific
mailing list or globally within the Mailman system.  Both explicit email
addresses and email address patterns can be banned.

Barry Warsaw's avatar
Barry Warsaw committed
9
10
11
Bans are managed through the `Ban Manager`.  There are ban managers for
specific lists, and there is a global ban manager.  To get access to the
global ban manager, adapt ``None``.
12
13

    >>> from mailman.interfaces.bans import IBanManager
Barry Warsaw's avatar
Barry Warsaw committed
14
    >>> global_bans = IBanManager(None)
15

Barry Warsaw's avatar
Barry Warsaw committed
16
At first, no email addresses are banned globally.
17

Barry Warsaw's avatar
Barry Warsaw committed
18
    >>> global_bans.is_banned('anne@example.com')
19
20
    False

Barry Warsaw's avatar
Barry Warsaw committed
21
To get a list-specific ban manager, adapt the mailing list object.
22

23
    >>> from mailman.app.lifecycle import create_list
Barry Warsaw's avatar
Barry Warsaw committed
24
25
26
27
28
29
    >>> mlist = create_list('test@example.com')
    >>> test_bans = IBanManager(mlist)

There are no bans for this particular list.

    >>> test_bans.is_banned('bart@example.com')
30
31
32
33
34
35
36
    False


Specific bans
=============

An email address can be banned from a specific mailing list by adding a ban to
Barry Warsaw's avatar
Barry Warsaw committed
37
the list's ban manager.
38

Barry Warsaw's avatar
Barry Warsaw committed
39
40
    >>> test_bans.ban('cris@example.com')
    >>> test_bans.is_banned('cris@example.com')
41
    True
Barry Warsaw's avatar
Barry Warsaw committed
42
    >>> test_bans.is_banned('bart@example.com')
43
44
45
46
    False

However, this is not a global ban.

Barry Warsaw's avatar
Barry Warsaw committed
47
    >>> global_bans.is_banned('cris@example.com')
48
49
50
51
52
53
54
55
56
    False


Global bans
===========

An email address can be banned globally, so that it cannot be subscribed to
any mailing list.

Barry Warsaw's avatar
Barry Warsaw committed
57
    >>> global_bans.ban('dave@example.com')
58

Barry Warsaw's avatar
Barry Warsaw committed
59
Because there is a global ban, Dave is also banned from the mailing list.
60

Barry Warsaw's avatar
Barry Warsaw committed
61
    >>> test_bans.is_banned('dave@example.com')
62
63
    True

Barry Warsaw's avatar
Barry Warsaw committed
64
65
Even when a new mailing list is created, Dave is still banned from this list
because of his global ban.
66

Barry Warsaw's avatar
Barry Warsaw committed
67
68
69
    >>> sample = create_list('sample@example.com')
    >>> sample_bans = IBanManager(sample)
    >>> sample_bans.is_banned('dave@example.com')
70
71
    True

Barry Warsaw's avatar
Barry Warsaw committed
72
Dave is of course banned globally.
73

Barry Warsaw's avatar
Barry Warsaw committed
74
    >>> global_bans.is_banned('dave@example.com')
75
76
77
78
    True

Cris however is not banned globally.

Barry Warsaw's avatar
Barry Warsaw committed
79
    >>> global_bans.is_banned('cris@example.com')
80
81
82
83
    False

Even though Cris is not banned globally, we can add a global ban for her.

Barry Warsaw's avatar
Barry Warsaw committed
84
85
    >>> global_bans.ban('cris@example.com')
    >>> global_bans.is_banned('cris@example.com')
86
87
    True

Barry Warsaw's avatar
Barry Warsaw committed
88
Cris is now banned from all mailing lists.
89

Barry Warsaw's avatar
Barry Warsaw committed
90
    >>> test_bans.is_banned('cris@example.com')
91
    True
Barry Warsaw's avatar
Barry Warsaw committed
92
    >>> sample_bans.is_banned('cris@example.com')
93
94
    True

Barry Warsaw's avatar
Barry Warsaw committed
95
96
We can remove the global ban to once again just ban her address from just the
test list.
97

Barry Warsaw's avatar
Barry Warsaw committed
98
99
100
101
    >>> global_bans.unban('cris@example.com')
    >>> global_bans.is_banned('cris@example.com')
    False
    >>> test_bans.is_banned('cris@example.com')
102
    True
Barry Warsaw's avatar
Barry Warsaw committed
103
    >>> sample_bans.is_banned('cris@example.com')
104
105
106
107
108
109
110
111
112
113
114
    False


Regular expression bans
=======================

Entire email address patterns can be banned, both for a specific mailing list
and globally, just as specific addresses can be banned.  Use this for example,
when an entire domain is a spam faucet.  When using a pattern, the email
address must start with a caret (^).

Barry Warsaw's avatar
Barry Warsaw committed
115
    >>> test_bans.ban('^.*@example.org')
116

Barry Warsaw's avatar
Barry Warsaw committed
117
Now, no one from example.org can subscribe to the test mailing list.
118

Barry Warsaw's avatar
Barry Warsaw committed
119
    >>> test_bans.is_banned('elle@example.org')
120
    True
Barry Warsaw's avatar
Barry Warsaw committed
121
    >>> test_bans.is_banned('eperson@example.org')
122
    True
Barry Warsaw's avatar
Barry Warsaw committed
123
124
125
126

example.com addresses are not banned.

    >>> test_bans.is_banned('elle@example.com')
127
128
    False

Barry Warsaw's avatar
Barry Warsaw committed
129
130
example.org addresses are not banned globally, nor for any other mailing
list.
131

Barry Warsaw's avatar
Barry Warsaw committed
132
    >>> sample_bans.is_banned('elle@example.org')
133
    False
Barry Warsaw's avatar
Barry Warsaw committed
134
    >>> global_bans.is_banned('elle@example.org')
135
136
137
138
    False

Of course, we can ban everyone from example.org globally too.

Barry Warsaw's avatar
Barry Warsaw committed
139
140
    >>> global_bans.ban('^.*@example.org')
    >>> sample_bans.is_banned('elle@example.org')
141
    True
Barry Warsaw's avatar
Barry Warsaw committed
142
    >>> global_bans.is_banned('elle@example.org')
143
144
145
146
147
    True

We can remove the mailing list ban on the pattern, though the global ban will
still be in place.

Barry Warsaw's avatar
Barry Warsaw committed
148
149
    >>> test_bans.unban('^.*@example.org')
    >>> test_bans.is_banned('elle@example.org')
150
    True
Barry Warsaw's avatar
Barry Warsaw committed
151
    >>> sample_bans.is_banned('elle@example.org')
152
    True
Barry Warsaw's avatar
Barry Warsaw committed
153
    >>> global_bans.is_banned('elle@example.org')
154
155
156
157
158
    True

But once the global ban is removed, everyone from example.org can subscribe to
the mailing lists.

Barry Warsaw's avatar
Barry Warsaw committed
159
160
    >>> global_bans.unban('^.*@example.org')
    >>> test_bans.is_banned('elle@example.org')
161
    False
Barry Warsaw's avatar
Barry Warsaw committed
162
    >>> sample_bans.is_banned('elle@example.org')
163
    False
Barry Warsaw's avatar
Barry Warsaw committed
164
    >>> global_bans.is_banned('elle@example.org')
165
166
167
168
169
170
171
172
    False


Adding and removing bans
========================

It is not an error to add a ban more than once.  These are just ignored.

Barry Warsaw's avatar
Barry Warsaw committed
173
174
175
    >>> test_bans.ban('fred@example.com')
    >>> test_bans.ban('fred@example.com')
    >>> test_bans.is_banned('fred@example.com')
176
177
178
179
    True

Nor is it an error to remove a ban more than once.

Barry Warsaw's avatar
Barry Warsaw committed
180
181
182
    >>> test_bans.unban('fred@example.com')
    >>> test_bans.unban('fred@example.com')
    >>> test_bans.is_banned('fred@example.com')
183
    False