path: root/src/mailman/model/docs/subscriptions.rst

===============
 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('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.workflows.subscription import OpenSubscriptionPolicy
    >>> mlist.subscription_policy = OpenSubscriptionPolicy

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.

    >>> from mailman.workflows.subscription import ModerationSubscriptionPolicy
    >>> mlist.subscription_policy = ModerationSubscriptionPolicy

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.

    >>> from mailman.workflows.unsubscription import OpenUnsubscriptionPolicy
    >>> mlist.unsubscription_policy = OpenUnsubscriptionPolicy
    >>> 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.

    >>> from mailman.workflows.unsubscription import ConfirmUnsubscriptionPolicy
    >>> mlist.unsubscription_policy = ConfirmUnsubscriptionPolicy
    >>> 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 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: 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...

    >>> 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