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.

>>> mlist = create_list('[email protected]')
>>> 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(
...     '[email protected]', '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('[email protected]'))
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 <[email protected]> on [email protected]
    as MemberRole.member>
>>> mlist.members.get_member('[email protected]')
<Member: Anne Person <[email protected]> on [email protected]
    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(
...     '[email protected]', '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('[email protected]'))
None

When the moderator confirms Bart’s subscription, he joins the mailing list.

>>> token, token_owner, member = manager.confirm(token)
>>> member
<Member: Bart Person <[email protected]> on [email protected]
    as MemberRole.member>
>>> mlist.members.get_member('[email protected]')
<Member: Bart Person <[email protected]> on [email protected]
    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('[email protected]'))
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('[email protected]')
<Member: Bart Person <[email protected]> on [email protected]
    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('[email protected]'))
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('[email protected]')
>>> cat = create_list('[email protected]')

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='[email protected]')
>>> 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 <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Cris Person <[email protected]>
    on [email protected] 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 <[email protected]>
    on [email protected] as MemberRole.owner>

There is an iteration shorthand for getting all the members.

>>> for member in service:
...     print(member)
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Cris Person <[email protected]>
    on [email protected] 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('[email protected]'):
...     print(member)
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.owner>

There may be no matching memberships.

>>> list(service.find_members('[email protected]'))
[]

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 <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Cris Person <[email protected]>
    on [email protected] 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 <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Anne Person <[email protected]>
    on [email protected] 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 <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] 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(
...         '[email protected]', 'ant.example.com'):
...     print(member)
<Member: Bart Person <[email protected]>
    on [email protected] 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 <[email protected]>
    on [email protected] as MemberRole.owner>

You can also find a specific membership by all three criteria.

>>> for member in service.find_members(
...         '[email protected]', 'bee.example.com', MemberRole.owner):
...     print(member)
<Member: Bart Person <[email protected]>
    on [email protected] 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('[email protected]'))
None

But if there is exactly one membership, it is returned.

>>> service.find_member('[email protected]', 'ant.example.com')
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>

Removing members

Members can be removed via this service.

>>> len(service.get_members())
6
>>> service.leave('cat.example.com', '[email protected]')
>>> len(service.get_members())
5
>>> for member in service:
...     print(member)
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Anne Person <[email protected]>
    on [email protected] 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 <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Cris Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Anne Person <[email protected]>
    on [email protected] 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('[email protected]'))
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', [
...         '[email protected]',
...         '[email protected]',
...         '[email protected]',
...         ])

There were some successes…

>>> dump_list(success)
[email protected]
[email protected]

…and some failures.

>>> dump_list(fail)
[email protected]

And now there are 5 memberships again.

>>> for member in service:
...     print(member)
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.moderator>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.member>
<Member: Bart Person <[email protected]>
    on [email protected] as MemberRole.owner>
<Member: Anne Person <[email protected]>
    on [email protected] as MemberRole.member>
>>> len(service.get_members())
5