Subscriptions
When a user wants to join a mailing list, they must register and verify their
email address. Then depending on how the mailing list is configured, they may
need to confirm their subscription and have it approved by the list moderator.
The ISubscriptionManager
interface manages this work flow.
>>> from mailman.interfaces.subscriptions import ISubscriptionManager
To begin, adapt a mailing list to an ISubscriptionManager
. This is a
named interface because the same interface manages both subscriptions and
unsubscriptions.
>>> from mailman.app.lifecycle import create_list
>>> mlist = create_list('ant@example.com')
>>> manager = ISubscriptionManager(mlist)
Either addresses or users with a preferred address can be registered.
>>> from mailman.interfaces.usermanager import IUserManager
>>> from zope.component import getUtility
>>> anne = getUtility(IUserManager).create_address(
... 'anne@example.com', 'Anne Person')
Subscribing an email address
The subscription process requires that the email address be verified. It may also require confirmation or moderator approval depending on the mailing list’s subscription policy. For example, an open subscription policy does not require confirmation or approval, but the email address must still be verified, and the process will pause until these steps are completed.
>>> from mailman.interfaces.mailinglist import SubscriptionPolicy
>>> mlist.subscription_policy = SubscriptionPolicy.open
Anne attempts to join the mailing list. A unique token is created which represents this work flow.
>>> token, token_owner, member = manager.register(anne)
Because her email address has not yet been verified, she has not yet become a member of the mailing list.
>>> print(member)
None
>>> print(mlist.members.get_member('anne@example.com'))
None
Once she verifies her email address, she will become a member of the mailing list. When the subscription policy requires confirmation, the verification process implies that she also confirms her wish to join the mailing list.
>>> token, token_owner, member = manager.confirm(token)
>>> member
<Member: Anne Person <anne@example.com> on ant@example.com
as MemberRole.member>
>>> mlist.members.get_member('anne@example.com')
<Member: Anne Person <anne@example.com> on ant@example.com
as MemberRole.member>
Subscribing a user
Users can also register, but they must have a preferred address. The mailing list will deliver messages to this preferred address.
>>> bart = getUtility(IUserManager).make_user(
... 'bart@example.com', 'Bart Person')
Bart verifies his address and makes it his preferred address.
>>> from mailman.utilities.datetime import now
>>> preferred = list(bart.addresses)[0]
>>> preferred.verified_on = now()
>>> bart.preferred_address = preferred
The mailing list’s subscription policy does not require Bart to confirm his subscription, but the moderate does want to approve all subscriptions.
>>> mlist.subscription_policy = SubscriptionPolicy.moderate
Now when Bart registers as a user for the mailing list, a token will still be generated, but this is only used by the moderator. At first, Bart is not subscribed to the mailing list.
>>> token, token_owner, member = manager.register(bart)
>>> print(member)
None
>>> print(mlist.members.get_member('bart@example.com'))
None
When the moderator confirms Bart’s subscription, he joins the mailing list.
>>> token, token_owner, member = manager.confirm(token)
>>> member
<Member: Bart Person <bart@example.com> on ant@example.com
as MemberRole.member>
>>> mlist.members.get_member('bart@example.com')
<Member: Bart Person <bart@example.com> on ant@example.com
as MemberRole.member>
Unsubscribing
Similarly, unsubscribing a user depends on the mailing list’s unsubscription policy. Of course, since the address or user is already subscribed, implying that their email address is already verified, that step is not required. To begin with unsubscribing, you need to adapt the mailing list to the same interface, but with a different name.
>>> manager = ISubscriptionManager(mlist)
If the mailing list’s unsubscription policy is open, unregistering the subscription takes effect immediately.
>>> mlist.unsubscription_policy = SubscriptionPolicy.open
>>> token, token_owner, member = manager.unregister(anne)
>>> print(mlist.members.get_member('anne@example.com'))
None
Usually though, the member must confirm their unsubscription request, to prevent an attacker from unsubscribing them from the list without their knowledge.
>>> mlist.unsubscription_policy = SubscriptionPolicy.confirm
>>> token, token_owner, member = manager.unregister(bart)
Bart hasn’t confirmed yet, so he’s still a member of the list.
>>> mlist.members.get_member('bart@example.com')
<Member: Bart Person <bart@example.com> on ant@example.com
as MemberRole.member>
Once Bart confirms, he’s unsubscribed from the mailing list.
>>> token, token_owner, member = manager.confirm(token)
>>> print(mlist.members.get_member('bart@example.com'))
None
Subscription services
The ISubscriptionService
utility provides higher level convenience methods
useful for searching, retrieving, iterating, and removing memberships across
all mailing lists on the system.
>>> from mailman.interfaces.subscriptions import ISubscriptionService
>>> service = getUtility(ISubscriptionService)
You can use the service to get all members of all mailing lists, for any membership role. At first, there are no memberships.
>>> service.get_members()
[]
>>> sum(1 for member in service)
0
>>> from uuid import UUID
>>> print(service.get_member(UUID(int=801)))
None
Listing members
When there are some members, of any role on any mailing list, they can be retrieved through the subscription service.
>>> from mailman.app.lifecycle import create_list
>>> ant = mlist
>>> bee = create_list('bee@example.com')
>>> cat = create_list('cat@example.com')
Some people become members.
>>> from mailman.interfaces.member import MemberRole
>>> from mailman.testing.helpers import subscribe
>>> anne_1 = subscribe(ant, 'Anne')
>>> anne_2 = subscribe(ant, 'Anne', MemberRole.owner)
>>> bart_1 = subscribe(ant, 'Bart', MemberRole.moderator)
>>> bart_2 = subscribe(bee, 'Bart', MemberRole.owner)
>>> anne_3 = subscribe(cat, 'Anne', email='anne@example.com')
>>> cris_1 = subscribe(cat, 'Cris')
The service can be used to iterate over them.
>>> for member in service.get_members():
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
<Member: Anne Person <anne@example.com>
on cat@example.com as MemberRole.member>
<Member: Cris Person <cperson@example.com>
on cat@example.com as MemberRole.member>
The service can also be used to get the information about a single member.
>>> print(service.get_member(bart_2.member_id))
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
There is an iteration shorthand for getting all the members.
>>> for member in service:
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
<Member: Anne Person <anne@example.com>
on cat@example.com as MemberRole.member>
<Member: Cris Person <cperson@example.com>
on cat@example.com as MemberRole.member>
Searching for members
The subscription service can be used to find memberships based on specific
search criteria. For example, we can find all the mailing lists that Anne is
a member of with her aperson@example.com
address.
>>> for member in service.find_members('aperson@example.com'):
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
There may be no matching memberships.
>>> list(service.find_members('dave@example.com'))
[]
The address may contain asterisks, which will be interpreted as a wildcard in the search pattern for their email address or display name.
>>> for member in service.find_members('*person*'):
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
<Member: Anne Person <anne@example.com>
on cat@example.com as MemberRole.member>
<Member: Cris Person <cperson@example.com>
on cat@example.com as MemberRole.member>
Memberships can also be searched for by user id.
>>> for member in service.find_members(anne_1.user.user_id):
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
You can find all the memberships for a specific mailing list.
>>> for member in service.find_members(list_id='ant.example.com'):
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
You can find all the memberships for an address on a specific mailing list, but you have to give it the list id, not the fqdn listname since the former is stable but the latter could change if the list is moved.
>>> for member in service.find_members(
... 'bperson@example.com', 'ant.example.com'):
... print(member)
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
You can find all the memberships for an address with a specific role.
>>> for member in service.find_members(
... list_id='ant.example.com', role=MemberRole.owner):
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
You can also find a specific membership by all three criteria.
>>> for member in service.find_members(
... 'bperson@example.com', 'bee.example.com', MemberRole.owner):
... print(member)
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
Finding a single member
If you expect only zero or one member to match your criteria, you can use a
the more efficient find_member()
method. This takes exactly the same
criteria as find_members()
.
There may be no matching members.
>>> print(service.find_member('dave@example.com'))
None
But if there is exactly one membership, it is returned.
>>> service.find_member('bperson@example.com', 'ant.example.com')
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
Removing members
Members can be removed via this service.
>>> len(service.get_members())
6
>>> service.leave('cat.example.com', 'cperson@example.com')
>>> len(service.get_members())
5
>>> for member in service:
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
<Member: Anne Person <anne@example.com>
on cat@example.com as MemberRole.member>
Mass Removal
The subscription service can be used to perform mass removals. You are required to pass the list id of the respective mailing list and a list of email addresses to be removed.
>>> bart_2 = subscribe(ant, 'Bart')
>>> cris_2 = subscribe(ant, 'Cris')
>>> for member in service:
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Cris Person <cperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
<Member: Anne Person <anne@example.com>
on cat@example.com as MemberRole.member>
There are now two more memberships.
>>> len(service.get_members())
7
But this address is not subscribed to any mailing list.
>>> print(service.find_member('bogus@example.com'))
None
We can unsubscribe some addresses from the ant mailing list. Note that even
though Anne is subscribed several times, only her ant membership with role
member
will be removed.
>>> success, fail = service.unsubscribe_members(
... 'ant.example.com', [
... 'aperson@example.com',
... 'cperson@example.com',
... 'bogus@example.com',
... ])
There were some successes…
>>> from mailman.testing.documentation import dump_list
>>> dump_list(success)
aperson@example.com
cperson@example.com
…and some failures.
>>> dump_list(fail)
bogus@example.com
And now there are 5 memberships again.
>>> for member in service:
... print(member)
<Member: Anne Person <aperson@example.com>
on ant@example.com as MemberRole.owner>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.moderator>
<Member: Bart Person <bperson@example.com>
on ant@example.com as MemberRole.member>
<Member: Bart Person <bperson@example.com>
on bee@example.com as MemberRole.owner>
<Member: Anne Person <anne@example.com>
on cat@example.com as MemberRole.member>
>>> len(service.get_members())
5