1=========================
2 Subscription moderation
3=========================
4
5Subscription (and sometimes unsubscription) requests can similarly be
6accepted, discarded, rejected, or deferred by the list moderators.
7
8
9Viewing subscription requests
10=============================
11
12A mailing list starts with no pending subscription or unsubscription requests.
13
14    >>> ant = create_list('ant@example.com')
15    >>> ant.admin_immed_notify = False
16    >>> from mailman.interfaces.mailinglist import SubscriptionPolicy
17    >>> ant.subscription_policy = SubscriptionPolicy.moderate
18    >>> transaction.commit()
19    >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com/requests')
20    http_etag: "..."
21    start: 0
22    total_size: 0
23
24When Anne tries to subscribe to the Ant list, her subscription is held for
25moderator approval.  Her email address is pre-verified and her subscription
26request is pre-confirmed, but because the mailing list is moderated, a token
27is returned to track her subscription request.
28
29    >>> dump_json('http://localhost:9001/3.0/members', {
30    ...           'list_id': 'ant.example.com',
31    ...           'subscriber': 'anne@example.com',
32    ...           'display_name': 'Anne Person',
33    ...           'pre_verified': True,
34    ...           'pre_confirmed': True,
35    ...           })
36    http_etag: ...
37    token: 0000000000000000000000000000000000000001
38    token_owner: moderator
39
40The subscription request can be viewed in the REST API.
41
42    >>> transaction.commit()
43    >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com/requests')
44    entry 0:
45        display_name: Anne Person
46        email: anne@example.com
47        http_etag: "..."
48        list_id: ant.example.com
49        token: 0000000000000000000000000000000000000001
50        token_owner: moderator
51        type: subscription
52        when: 2005-08-01T07:49:23
53    http_etag: "..."
54    start: 0
55    total_size: 1
56
57
58Viewing individual requests
59===========================
60
61You can view an individual membership change request by providing the token
62(a.k.a. request id).  Anne's subscription request looks like this.
63
64    >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com/'
65    ...           'requests/0000000000000000000000000000000000000001')
66    display_name: Anne Person
67    email: anne@example.com
68    http_etag: "..."
69    list_id: ant.example.com
70    token: 0000000000000000000000000000000000000001
71    token_owner: moderator
72    type: subscription
73    when: 2005-08-01T07:49:23
74
75
76Disposing of subscription requests
77==================================
78
79Moderators can dispose of held subscription requests by POSTing back to the
80request's resource.  The POST data requires an action of one of the following:
81
82 * discard - throw the request away.
83 * reject - the request is denied and a notification is sent to the email
84            address requesting the membership change.
85 * defer - defer any action on this membership change (continue to hold it).
86 * accept - accept the membership change.
87
88Anne's subscription request is accepted.
89
90    >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com/requests'
91    ...           '/0000000000000000000000000000000000000001',
92    ...           {'action': 'accept'})
93    date: ...
94    server: ...
95    status: 204
96
97Anne is now a member of the mailing list.
98
99    >>> ant.members.get_member('anne@example.com')
100    <Member: Anne Person <anne@example.com> on ant@example.com
101             as MemberRole.member>
102
103There are no more membership change requests.
104
105    >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com/requests')
106    http_etag: "..."
107    start: 0
108    total_size: 0
109