=============
Mailing lists
=============

The REST API can be queried for the set of known mailing lists.  There is a
top level collection that can return all the mailing lists.  There aren't any
yet though.

    >>> dump_json('http://localhost:8001/3.0/lists')
    resource_type_link: http://localhost:8001/3.0/#lists
    start: None
    total_size: 0

Create a mailing list in a domain and it's accessible via the API.

    >>> create_list('test-one@example.com')
    <mailing list "test-one@example.com" at ...>
    >>> transaction.commit()

    >>> dump_json('http://localhost:8001/3.0/lists')
    entry 0:
        fqdn_listname: test-one@example.com
        host_name: example.com
        http_etag: "..."
        list_name: test-one
        real_name: Test-one
        resource_type_link: http://localhost:8001/3.0/#list
        self_link: http://localhost:8001/3.0/lists/test-one@example.com
    resource_type_link: http://localhost:8001/3.0/#lists
    start: 0
    total_size: 1


Creating lists via the API
==========================

New mailing lists can also be created through the API, by posting to the
'lists' URL.  However lazr.restful requires us to use a 'named operation'
instead of posting directly to the URL.

    >>> dump_json('http://localhost:8001/3.0/lists', {
    ...           'ws.op': 'new',
    ...           'fqdn_listname': 'test-two@example.com',
    ...           })
    URL: http://localhost:8001/3.0/lists
    content-length: 0
    content-type: text/plain;charset=utf-8
    date: ...
    location: http://localhost:8001/3.0/lists/test-two@example.com
    server: WSGIServer/... Python/...
    x-content-type-warning: guessed from content
    x-powered-by: Zope (www.zope.org), Python (www.python.org)

The mailing list exists in the database.

    >>> from mailman.interfaces.listmanager import IListManager
    >>> from zope.component import getUtility
    >>> getUtility(IListManager).get('test-two@example.com')
    <mailing list "test-two@example.com" at ...>

    # The above starts a Storm transaction, which will lock the database
    # unless we abort it.
    >>> transaction.abort()

It is also available via the location given in the response.

    >>> dump_json('http://localhost:8001/3.0/lists/test-two@example.com')
    fqdn_listname: test-two@example.com
    host_name: example.com
    http_etag: "..."
    list_name: test-two
    real_name: Test-two
    resource_type_link: http://localhost:8001/3.0/#list
    self_link: http://localhost:8001/3.0/lists/test-two@example.com

However, you are not allowed to create a mailing list in a domain that does
not exist.

    >>> dump_json('http://localhost:8001/3.0/lists', {
    ...           'ws.op': 'new',
    ...           'fqdn_listname': 'test-three@example.org',
    ...           })
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 400: Bad Request

Nor can you create a mailing list that already exists.

    >>> dump_json('http://localhost:8001/3.0/lists', {
    ...           'ws.op': 'new',
    ...           'fqdn_listname': 'test-one@example.com',
    ...           })
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 400: Bad Request