### Initialize AsyncClient with httpx

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Demonstrates how to initialize the AsyncClient using httpx as the HTTP client and asyncio for running asynchronous operations. This setup is necessary to interact with the Mailman Core API asynchronously.

```python
import httpx
from mailmanclient.asynclient import AsyncClient
import asyncio

async def main():
    conn = httpx.AsyncClient()
    client = AsyncClient(conn, 'http://localhost:8001/3.1',
                         'restadmin', 'restpass')
    domains = await client.domains()
    print(domains)

if __name__ == '__main__':
    asyncio.run(main())
```

--------------------------------

### Get Mailman System Information

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Fetches general system information about the Mailman Core installation. This includes details about the Mailman version and configuration.

```python
system_info = await client.system()
```

--------------------------------

### Initialize Mailman Client and Get System Info (Python)

Source: https://context7.com/mailman/mailmanclient/llms.txt

Demonstrates how to initialize the Mailman Client with API credentials and URL, then retrieve system information like version and API version. It also shows how to access global preferences and lists of available pipelines, chains, and styles.

```python
from mailmanclient import Client

# Initialize the client (production typically uses port 8001)
client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')

# Get system information
system_info = client.system
print(f"Mailman version: {system_info['mailman_version']}")
print(f"API version: {system_info['api_version']}")

# Access global system preferences (read-only)
global_prefs = client.preferences
print(f"Default language: {global_prefs['preferred_language']}")
print(f"Delivery mode: {global_prefs['delivery_mode']}")

# Get available pipelines and chains
pipelines = client.pipelines['pipelines']
chains = client.chains['chains']
print(f"Available pipelines: {pipelines}")
print(f"Available chains: {chains}")

# List available mailing list styles
styles = client.styles
for style in styles['styles']:
    print(f"{style['name']}: {style['description']}")
print(f"Default style: {styles['default']}")
```

--------------------------------

### GET /<api>/system

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves system-wide information for Mailman.

```APIDOC
## GET /<api>/system

### Description
Retrieves system information for Mailman.

### Method
GET

### Endpoint
`/<api>/system`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **system_info** (Mapping[str, Any]) - A dictionary containing system information.
```

--------------------------------

### Manage Mailman Users (Python)

Source: https://context7.com/mailman/mailmanclient/llms.txt

Provides comprehensive examples for managing users within the Mailman system. This includes creating, retrieving, listing, searching, updating, and deleting users, as well as managing their email addresses and subscriptions.

```Python
from mailmanclient import Client

client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')

# Create a new user
user = client.create_user(
    email='newuser@example.com',
    password='securepassword',
    display_name='New User'
)
print(f"Created user: {user.display_name}, ID: {user.user_id}")

# Get an existing user by email
user = client.get_user('user@example.com')
print(f"User: {user.display_name}")
print(f"Created on: {user.created_on}")

# List all users
for user in client.users:
    print(f"{user.display_name} ({user.user_id})")

# Paginated user listing
page = client.get_user_page(count=20, page=1)
for user in page:
    print(user.display_name)
page = page.next

# Search for users
users = client.find_users('john')  # Case-insensitive search
for user in users:
    print(f"Found: {user.display_name}")

# Paginated search
page = client.find_users_page(query='john', count=10, page=1)

# Update user attributes
user.display_name = 'Updated Name'
user.password = 'newpassword'  # Special handling for password
user.save()

# Get user's addresses
for address in user.addresses:
    print(f"Address: {address}, Verified: {address.verified}")

# Add additional address to user
new_addr = user.add_address('alternate@example.com')

# Add address and merge if it exists
merged_addr = user.add_address('other@example.com', absorb_existing=True)

# Manage preferred address
user.preferred_address = 'primary@example.com'
print(f"Preferred: {user.preferred_address}")
user.preferred_address = None  # Unset

# Get user's subscriptions
for subscription in user.subscriptions:
    print(f"Subscribed to: {subscription.list_id} as {subscription.role}")

# Get list IDs only
for list_id in user.subscription_list_ids:
    print(f"List ID: {list_id}")

# User preferences
prefs = user.preferences
prefs['delivery_mode'] = 'mime_digests'
prefs.save()

# Delete user
user.delete()
```

--------------------------------

### Manage Mailman Domains (Python)

Source: https://context7.com/mailman/mailmanclient/llms.txt

Provides examples for managing domains within Mailman using the Mailman Client library. This includes creating new domains, listing all domains, retrieving specific domains, managing domain owners, listing associated mailing lists, and deleting domains.

```python
from mailmanclient import Client

client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')

# Create a new domain
domain = client.create_domain(
    mail_host='example.com',
    description='Example Organization Lists',
    owner='admin@example.com',
    alias_domain='lists.example.com'  # Optional alias for Postfix
)
print(f"Created domain: {domain.mail_host}")

# List all domains
for domain in client.domains:
    print(f"Domain: {domain.mail_host}, Description: {domain.description}")

# Get a specific domain
example_domain = client.get_domain('example.com')
print(f"Mail host: {example_domain.mail_host}")
print(f"Alias domain: {example_domain.alias_domain}")

# Get domain owners
for owner in example_domain.owners:
    print(f"Owner: {owner.display_name}")

# Add/remove domain owners
example_domain.add_owner('newadmin@example.com')
example_domain.remove_all_owners()

# List mailing lists in a domain
for mlist in example_domain.lists:
    print(f"List: {mlist.fqdn_listname}")

# Delete a domain
example_domain.delete()
# Or using client: client.delete_domain('example.com')
```

--------------------------------

### Template Management with Mailman Client

Source: https://context7.com/mailman/mailmanclient/llms.txt

Manages email templates at site, domain, and list levels. This example demonstrates how to access and iterate through site-level templates to view their names and URIs.

```python
from mailmanclient import Client

client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')

# Site-level templates
templates = client.templates
for template in templates:
    print(f"Template: {template.name}, URI: {template.uri}")
```

--------------------------------

### Use Mailman AsyncClient

Source: https://context7.com/mailman/mailmanclient/llms.txt

Provides an example of using the asynchronous Mailman Client for non-blocking operations in asynchronous Python applications. It demonstrates fetching system information, listing domains and lists, retrieving list configurations and members, managing users, and finding members with filters.

```python
import asyncio
import httpx
from mailmanclient.asynclient import AsyncClient

async def main():
    # Create async HTTP client
    async with httpx.AsyncClient() as http_client:
        client = AsyncClient(
            client=http_client,
            base_url='http://localhost:8001/3.1',
            user='restadmin',
            password='restpass'
        )

        # Get system info
        system = await client.system()
        print(f"Mailman version: {system['mailman_version']}")

        # List domains
        domains = await client.domains()
        for domain in domains:
            print(f"Domain: {domain.mail_host}")

        # List mailing lists
        lists = await client.lists()
        for mlist in lists:
            print(f"List: {mlist.fqdn_listname}")

            # Get list config
            config = await mlist.config()
            print(f"  Description: {config.get('description')}")

            # Get members
            members = await mlist.members()
            for member in members:
                print(f"  Member: {member.email}")

        # List all users
        users = await client.users()
        for user in users:
            print(f"User: {user.display_name}")

            # Get user addresses
            addresses = await user.addresses()
            for addr in addresses:
                print(f"  Address: {addr.email}")

        # Find members with filters
        members = await client.find_members(
            list_id='developers.example.com',
            role='member',
            delivery_status='enabled'
        )

        # Get all addresses
        addresses = await client.addresses()
        for addr in addresses:
            prefs = await addr.preferences()
            print(f"{addr.email}: {prefs}")

# Run async code
asyncio.run(main())
```

--------------------------------

### Access Mailman Configuration (Python)

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Shows how to access and iterate through Mailman Core's configuration options via the REST API. Configuration is read-only and exposed as dictionary-like objects. This example iterates through all configuration keys and then specifically through the 'mailman' configuration section.

```python
>>> cfg = client.configuration
>>> for key in sorted(cfg):
...     print(cfg[key].name)
ARC
antispam
archiver.mail_archive
archiver.master
archiver.mhonarc
archiver.prototype
bounces
database
devmode
digests
dmarc
language.ar
language.ast
language.bg
language.ca
language.cs
language.da
language.de
language.el
language.en
language.es
language.et
language.eu
language.fi
language.fr
language.gl
language.he
language.hr
language.hu
language.ia
language.it
language.ja
language.ko
language.lt
language.nl
language.no
language.pl
language.pt
language.pt_BR
language.ro
language.ru
language.sk
language.sl
language.sr
language.sv
language.tr
language.uk
language.vi
language.zh_CN
language.zh_TW
logging.archiver
logging.bounce
logging.config
logging.database
logging.debug
logging.error
logging.fromusenet
logging.gunicorn
logging.http
logging.locks
logging.mischief
logging.plugins
logging.root
logging.runner
logging.smtp
logging.subscribe
logging.task
logging.vette
mailman
mta
nntp
passwords
paths.dev
paths.fhs
paths.here
paths.local
plugin.master
runner.archive
runner.bad
runner.bounces
runner.command
runner.digest
runner.in
runner.lmtp
runner.nntp
runner.out
runner.pipeline
runner.rest
runner.retry
runner.shunt
runner.task
runner.virgin
shell
styles
urlpatterns
webservice
>>> for key in sorted(cfg['mailman']):
...     print('{} : {}'.format(key, cfg['mailman'][key]))
anonymous_list_keep_headers : ...
cache_life : 7d
check_max_size_on_filtered_message : no
default_language : en
ds_lifetime : 1d
email_commands_max_lines : 10
filter_report : no
filtered_messages_are_preservable : no
hold_digest : no
html_to_plain_text_command : /usr/bin/lynx -dump $filename
layout : here
listname_chars : [-_.0-9a-z]
masthead_threshold : 4
moderator_request_life : 180d
noreply_address : noreply
pending_request_life : 3d
post_hook : 
pre_hook : 
run_tasks_every : 1h
self_link : http://localhost:9001/3.1/system/configuration/mailman
sender_headers : from from_ reply-to sender
site_owner : changeme@example.com
```

--------------------------------

### GET /<api>/lists/<listid>/config

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the configuration settings for a specific mailing list.

```APIDOC
## GET /<api>/lists/<listid>/config

### Description
Retrieves the configuration settings for a specific mailing list.

### Method
GET

### Endpoint
`/<api>/lists/<listid>/config`

### Parameters
#### Path Parameters
- **listid** (str) - Required - The ID of the mailing list.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **config** (Config) - The configuration object for the mailing list.
```

--------------------------------

### GET /lists

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Retrieve a collection of mailing lists with support for pagination, filtering by advertisement status, and domain scoping.

```APIDOC
## GET /lists

### Description
Retrieves a list of mailing lists. Supports pagination and filtering by advertisement status or domain.

### Method
GET

### Endpoint
/lists

### Parameters
#### Query Parameters
- **count** (integer) - Optional - Number of items per page.
- **page** (integer) - Optional - Page number to retrieve.
- **advertised** (boolean) - Optional - Filter lists by advertisement status.
- **mail_host** (string) - Optional - Filter lists by domain.

### Response
#### Success Response (200)
- **lists** (array) - A list of mailing list objects.

#### Response Example
{
  "lists": [
    {"fqdn_listname": "test-1@example.com"},
    {"fqdn_listname": "test-2@example.com"}
  ]
}
```

--------------------------------

### Get Mailing List Configuration

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the configuration settings for a specific mailing list. This includes various parameters that control the behavior of the list.

```python
config = await mailing_list.config()
```

--------------------------------

### Manage List Settings - Python

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Access and modify list settings using a dictionary-like proxy object. Settings can be retrieved, updated, and saved persistently. The object also supports dictionary's get method for safe access.

```python
>>> settings = test_one.settings
>>> for attr in sorted(settings):
...     print(attr + ': ' + str(settings[attr]))
accept_these_nonmembers: []
acceptable_aliases: []
...
volume: 1
>>> print(settings['display_name'])
Test-1
>>> print(settings['fqdn_listname'])
test-1@example.com
>>> print(settings['description'])

>>> settings['description'] = 'A very meaningful description.'
>>> settings['display_name'] = 'Test Numero Uno'
>>> settings.save()
>>> settings_new = test_one.settings
>>> print(settings_new['description'])
A very meaningful description.
>>> print(settings_new['display_name'])
Test Numero Uno
>>> print(settings_new.get('OhNoIForgotTheKey',
...                        'HowGoodIPlacedOneUnderTheDoormat'))
HowGoodIPlacedOneUnderTheDoormat
```

--------------------------------

### Implement Mailman Request Hooks

Source: https://context7.com/mailman/mailmanclient/llms.txt

Demonstrates how to add custom request hooks to the Mailman Client for intercepting and modifying API requests. Examples include a logging hook to print request details and an authentication hook to add custom headers.

```python
from mailmanclient import Client

def logging_hook(params):
    """Log all API requests"""
    print(f"API Request: {params.get('method', 'GET')} {params.get('url')}")
    return params

def auth_hook(params):
    """Add custom headers"""
    if 'headers' not in params:
        params['headers'] = {}
    params['headers']['X-Custom-Header'] = 'value'
    return params

# Initialize client with hooks
client = Client(
    'http://localhost:8001/3.1',
    'restadmin',
    'restpass',
    request_hooks=[logging_hook, auth_hook]
)
```

--------------------------------

### AsyncClient Initialization

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Demonstrates how to initialize the AsyncClient with an httpx.AsyncClient, base URL, and authentication credentials.

```APIDOC
## AsyncClient Initialization

### Description
Initialize the `AsyncClient` with an HTTP client, base URL, and authentication.

### Method
Constructor

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
>>> import httpx
>>> conn = httpx.AsyncClient()
>>> from mailmanclient.asynclient import AsyncClient
>>> client = AsyncClient(conn, 'http://localhost:8001/3.1',
...                      'restadmin', 'restpass')
```

### Response
N/A
```

--------------------------------

### GET /<api>/lists

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves a list of all mailing lists.

```APIDOC
## GET /<api>/lists

### Description
Retrieves a list of all mailing lists.

### Method
GET

### Endpoint
`/<api>/lists`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **lists** (List[MailingList]) - A list of MailingList objects.
```

--------------------------------

### Create User - Python MailmanClient

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Illustrates the process of creating a new user with an email, password, and an optional display name. It also shows how to retrieve the newly created user and access their attributes.

```python
>>> ler = client.create_user(email='ler@primus.org',
...                          password='somepass',
...                          display_name='Ler')
>>> print(ler.display_name)
Ler
>>> ler = client.get_user('ler@primus.org')
>>> print(ler.password)
$...
>>> print(ler.display_name)
Ler
```

--------------------------------

### GET /<api>/domains

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves all configured domains in Mailman.

```APIDOC
## GET /<api>/domains

### Description
Retrieves a list of all domains configured in Mailman.

### Method
GET

### Endpoint
`/<api>/domains`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **domains** (List[Domain]) - A list of Domain objects.
```

--------------------------------

### Initialize Mailman Client

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Demonstrates how to instantiate the Mailman client by providing the REST API base URL, username, and password for Basic Authentication.

```python
from mailmanclient import Client
client = Client('http://localhost:9001/3.1', 'restadmin', 'restpass')
```

--------------------------------

### GET /<api>/users

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves a list of all users in Mailman Core.

```APIDOC
## GET /<api>/users

### Description
Fetches a list of all users in Mailman Core.

### Method
GET

### Endpoint
`/<api>/users`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **users** (List[User]) - A list of User objects.
```

--------------------------------

### GET /<api>/members

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves all members across all mailing lists.

```APIDOC
## GET /<api>/members

### Description
Fetches a list of all members in Mailman.

### Method
GET

### Endpoint
`/<api>/members`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **members** (List[Member]) - A list of Member objects.
```

--------------------------------

### Subscribe and Invite Members to Mailing Lists

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Demonstrates how to subscribe users to a mailing list, handle verification tokens for unverified or invited members, and use pre-verified or pre-confirmed flags for automated subscription flows.

```python
data = test_one.subscribe('unverified@example.com', 'Unverified')
data = test_one.subscribe('invitee@example.com', 'Invitee', invitation=True)
data = test_one.subscribe('unconfirmed@example.com', 'Unconfirmed', pre_verified=True)
print(test_one.subscribe('anna@example.com', 'Anna', pre_verified=True, pre_confirmed=True))
```

--------------------------------

### GET /<api>/address

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves all email addresses managed by Mailman.

```APIDOC
## GET /<api>/address

### Description
Fetches a list of all addresses in Mailman.

### Method
GET

### Endpoint
`/<api>/address`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **addresses** (List[Address]) - A list of Address objects.
```

--------------------------------

### Create and Inspect Mailing Lists (Python)

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Demonstrates how to create a new mailing list using the Mailman client and inspect its properties such as fully qualified domain name, mail host, list name, and display name. It also shows how to create a list with a specific style.

```python
>>> test_one = example.create_list('test-1')
>>> print(test_one.fqdn_listname)
test-1@example.com
>>> print(test_one.mail_host)
example.com
>>> print(test_one.list_name)
test-1
>>> print(test_one.display_name)
Test-1

>>> test_two = example.create_list('test-announce', style_name='legacy-announce')
>>> print(test_two.fqdn_listname)
test-announce@example.com
```

--------------------------------

### Create and Configure Mailing Lists (Python)

Source: https://context7.com/mailman/mailmanclient/llms.txt

Illustrates how to create and manage mailing lists within a Mailman domain using the Mailman Client. It covers creating lists, setting styles, retrieving existing lists, accessing and modifying list settings like description and subscription policy, listing all lists, filtering by advertised status, and updating settings.

```python
from mailmanclient import Client

client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')
domain = client.get_domain('example.com')

# Create a mailing list
my_list = domain.create_list('developers')
print(f"Created: {my_list.fqdn_listname}")  # developers@example.com
print(f"List ID: {my_list.list_id}")
print(f"Display name: {my_list.display_name}")

# Create list with a specific style
announce_list = domain.create_list('announcements', style_name='legacy-announce')

# Get an existing list
dev_list = client.get_list('developers@example.com')

# Access and modify list settings
settings = dev_list.settings
print(f"Description: {settings['description']}")
print(f"Subscription policy: {settings['subscription_policy']}")

# Update settings
settings['description'] = 'Developer discussion mailing list'
settings['display_name'] = 'Developers'
settings['subscription_policy'] = 'confirm_then_moderate'
settings['advertised'] = True
settings.save()

# List all mailing lists
for mlist in client.lists:
    print(f"{mlist.fqdn_listname} - Members: {mlist.member_count}")

# Get only advertised lists
for mlist in client.get_lists(advertised=True):
    print(f"Advertised: {mlist.fqdn_listname}")
```

--------------------------------

### GET /members/{list_id}/{email}

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Retrieve the details of a specific member from a mailing list.

```APIDOC
## GET /members/{list_id}/{email}

### Description
Retrieves the membership object for a given email address on a specific mailing list.

### Method
GET

### Endpoint
/members/{list_id}/{email}

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the mailing list.
- **email** (string) - Required - The email address of the member.

### Response
#### Success Response (200)
- **member** (object) - The membership details including preferences and user object.

#### Response Example
{
  "email": "cris@example.com",
  "list_id": "test-2.example.com",
  "preferences": { "delivery_mode": null, "acknowledge_posts": null },
  "user": { "display_name": "Cris", "user_id": 123 }
}
```

--------------------------------

### GET /<api>/users/<userid>/addresses

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves all email addresses associated with a specific user.

```APIDOC
## GET /<api>/users/<userid>/addresses

### Description
Retrieves all email addresses associated with a specific user.

### Method
GET

### Endpoint
`/<api>/users/<userid>/addresses`

### Parameters
#### Path Parameters
- **userid** (str) - Required - The ID of the user.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **addresses** (List[Address]) - A list of Address objects associated with the user.
```

--------------------------------

### Manage Subscription Requests - Python

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

This section illustrates how to subscribe users to a list, retrieve subscription requests, and check their details. It covers subscribing with different pre-confirmation settings and accessing request attributes like email, token, and date.

```python
>>> confirm_first.requests
[]
>>> data = confirm_first.subscribe('groucho@example.com',
...                                pre_verified=True,
...                                pre_confirmed=True)
>>> print(data['token_owner'])
moderator
```

```python
>>> import time; time.sleep(5)
>>> confirm_first.get_requests_count()
1
```

```python
>>> request_1 = confirm_first.requests[0]
>>> print(request_1['email'])
groucho@example.com
>>> print (request_1['token'] is not None)
True
>>> print(request_1['token_owner'])
moderator
>>> print(request_1['request_date'] is not None)
True
>>> print(request_1['list_id'])
confirm-first.example.com
```

--------------------------------

### GET /<api>/lists/<listid>/roster/owner

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the list of owners for a specific mailing list.

```APIDOC
## GET /<api>/lists/<listid>/roster/owner

### Description
Retrieves the list of owners for a specific mailing list.

### Method
GET

### Endpoint
`/<api>/lists/<listid>/roster/owner`

### Parameters
#### Path Parameters
- **listid** (str) - Required - The ID of the mailing list.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **owners** (List[Member]) - A list of Member objects who are owners.
```

--------------------------------

### Retrieve and List Mailing Lists (Python)

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Illustrates how to retrieve a specific mailing list by its address and how to iterate through all known mailing lists. It also demonstrates creating lists within a specific domain.

```python
>>> my_list = client.get_list('test-1@example.com')
>>> print(my_list.fqdn_listname)
test-1@example.com

>>> print(example.create_list('test-2').fqdn_listname)
test-2@example.com
>>> domain = client.get_domain('example.net')
>>> print(domain.create_list('test-3').fqdn_listname)
test-3@example.net
>>> print(example.create_list('test-3').fqdn_listname)
test-3@example.com

>>> for mlist in client.lists:
...     print(mlist.fqdn_listname)
test-1@example.com
test-2@example.com
test-3@example.com
test-3@example.net
test-announce@example.com
```

--------------------------------

### GET /<api>/lists/<listid>/roster/nonmember

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the list of non-members for a specific mailing list.

```APIDOC
## GET /<api>/lists/<listid>/roster/nonmember

### Description
Retrieves the list of non-members for a specific mailing list.

### Method
GET

### Endpoint
`/<api>/lists/<listid>/roster/nonmember`

### Parameters
#### Path Parameters
- **listid** (str) - Required - The ID of the mailing list.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **nonmembers** (List[Member]) - A list of Member objects who are non-members.
```

--------------------------------

### GET /<api>/lists/<listid>/roster/moderator

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the list of moderators for a specific mailing list.

```APIDOC
## GET /<api>/lists/<listid>/roster/moderator

### Description
Retrieves the list of moderators for a specific mailing list.

### Method
GET

### Endpoint
`/<api>/lists/<listid>/roster/moderator`

### Parameters
#### Path Parameters
- **listid** (str) - Required - The ID of the mailing list.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **moderators** (List[Member]) - A list of Member objects who are moderators.
```

--------------------------------

### Configure Subscription Policy - Python

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

This snippet demonstrates how to create a new mailing list and set its subscription policy to 'confirm_then_moderate'. It shows how to access and modify list settings and save the changes.

```python
>>> confirm_first = example_dot_com.create_list('confirm-first')
>>> settings = confirm_first.settings
>>> settings['subscription_policy'] = 'confirm_then_moderate'
>>> settings.save()
```

```python
>>> confirm_first = client.get_list('confirm-first.example.com')
>>> print(confirm_first.settings['subscription_policy'])
confirm_then_moderate
```

--------------------------------

### GET /<api>/lists/<listid>/roster/member

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the list of members (subscribers) for a specific mailing list.

```APIDOC
## GET /<api>/lists/<listid>/roster/member

### Description
Retrieves the list of members (subscribers) for a specific mailing list.

### Method
GET

### Endpoint
`/<api>/lists/<listid>/roster/member`

### Parameters
#### Path Parameters
- **listid** (str) - Required - The ID of the mailing list.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **members** (List[Member]) - A list of Member objects who are subscribers.
```

--------------------------------

### Client Initialization and System Information

Source: https://context7.com/mailman/mailmanclient/llms.txt

Initializes the Mailman Client and retrieves basic system information, preferences, pipelines, chains, and mailing list styles.

```APIDOC
## Client Initialization and System Information

### Description
Initializes the Mailman Client and demonstrates how to retrieve system information, global preferences, available pipelines and chains, and mailing list styles.

### Method
N/A (Client Initialization)

### Endpoint
N/A (Client Initialization)

### Parameters
N/A

### Request Example
```python
from mailmanclient import Client

# Initialize the client (production typically uses port 8001)
client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')

# Get system information
system_info = client.system
print(f"Mailman version: {system_info['mailman_version']}")
print(f"API version: {system_info['api_version']}")

# Access global system preferences (read-only)
global_prefs = client.preferences
print(f"Default language: {global_prefs['preferred_language']}")
print(f"Delivery mode: {global_prefs['delivery_mode']}")

# Get available pipelines and chains
pipelines = client.pipelines['pipelines']
chains = client.chains['chains']
print(f"Available pipelines: {pipelines}")
print(f"Available chains: {chains}")

# List available mailing list styles
styles = client.styles
for style in styles['styles']:
    print(f"{style['name']}: {style['description']}")
print(f"Default style: {styles['default']}")
```

### Response
#### Success Response (200)
N/A (This is a client-side initialization and data retrieval example)

#### Response Example
```json
{
  "mailman_version": "3.3.0",
  "api_version": "3.1",
  "preferred_language": "en",
  "delivery_mode": "normal",
  "pipelines": ["pipeline1", "pipeline2"],
  "chains": ["chain1", "chain2"],
  "styles": {
    "styles": [
      {"name": "legacy-normal", "description": "Legacy normal list style"},
      {"name": "legacy-announce", "description": "Legacy announcement list style"}
    ],
    "default": "legacy-normal"
  }
}
```
```

--------------------------------

### Running Async Client Methods

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Shows how to execute asynchronous methods of the AsyncClient using an asyncio event loop.

```APIDOC
## Running Async Client Methods

### Description
Execute asynchronous client methods within an asyncio event loop.

### Method
`asyncio.run()`

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
>>> import asyncio
>>> domains = asyncio.run(client.domains())
```

### Response
Returns the result of the awaited asynchronous method.
```

--------------------------------

### GET /<api>/lists/<listid>/roster/<role>

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the roster for a specific mailing list based on role.

```APIDOC
## GET /<api>/lists/<listid>/roster/<role>

### Description
Retrieves the roster of members for a specific mailing list, filtered by role.

### Method
GET

### Endpoint
`/<api>/lists/<listid>/roster/<role>`

### Parameters
#### Path Parameters
- **listid** (str) - Required - The ID of the mailing list.
- **role** (str) - Required - The role to filter the roster by (e.g., 'member', 'owner').

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **roster** (List[Member]) - A list of Member objects belonging to the specified role.
```

--------------------------------

### Manage Mailman Templates

Source: https://context7.com/mailman/mailmanclient/llms.txt

Demonstrates how to set and retrieve site-level, domain-level, and list-level templates using the Mailman Client. It covers setting templates with optional authentication and paginating requests for site templates.

```python
client.set_template(
    template_name='list:member:regular:header',
    url='http://templates.example.com/header.txt',
    username='user',      # Optional auth
    password='pass'
)

# Paginated site templates
page = client.get_templates_page(count=10, page=1)

# Domain-level templates
domain = client.get_domain('example.com')
domain_templates = domain.templates

domain.set_template(
    template_name='list:member:regular:footer',
    uri='http://templates.example.com/footer.txt'
)

# List-level templates
mlist = client.get_list('developers@example.com')
list_templates = mlist.templates

mlist.set_template(
    template_name='list:user:notice:welcome',
    uri='http://templates.example.com/welcome.txt',
    username='user',
    password='pass'
)
```

--------------------------------

### Get Mailing List Moderators

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the moderators for a specific mailing list. Moderators have special privileges for managing the list.

```python
moderators = await mailing_list.moderators()
```

--------------------------------

### Subscription Management with MailmanClient

Source: https://context7.com/mailman/mailmanclient/llms.txt

Covers various subscription management operations including subscribing users with different verification levels, sending invitations, unsubscribing members, and performing mass unsubscribes. It highlights options for pre-verification, confirmation bypass, and admin-added subscriptions.

```python
from mailmanclient import Client

client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')
mlist = client.get_list('developers@example.com')

# Subscribe with full verification/confirmation workflow
result = mlist.subscribe('newuser@example.com', display_name='New User')
if 'token' in result:
    print(f"Subscription pending, token: {result['token']}")
    print(f"Token owner: {result['token_owner']}")  # 'subscriber' or 'moderator'

# Subscribe with pre-verification (bypass email verification)
member = mlist.subscribe(
    'verified@example.com',
    display_name='Verified User',
    pre_verified=True,
    pre_confirmed=True  # User has confirmed subscription
)
print(f"Subscribed: {member}")

# Subscribe with full bypass (admin action)
member = mlist.subscribe(
    'admin-added@example.com',
    display_name='Admin Added',
    pre_verified=True,
    pre_confirmed=True,
    pre_approved=True,  # Moderator approved
    send_welcome_message=False,
    delivery_mode='regular',  # or 'plaintext_digests', 'mime_digests'
    delivery_status='enabled'
)

# Send an invitation
result = mlist.subscribe(
    'invitee@example.com',
    display_name='Invited User',
    invitation=True
)

# Unsubscribe a member
mlist.unsubscribe('user@example.com')

# Unsubscribe with confirmation bypass
mlist.unsubscribe('user@example.com', pre_confirmed=True, pre_approved=True)

# Mass unsubscribe
emails = ['user1@example.com', 'user2@example.com', 'user3@example.com']
result = mlist.mass_unsubscribe(emails)
# Returns dict mapping emails to success status

# Unsubscribe via member object
member = mlist.get_member('user@example.com')
member.unsubscribe()
```

--------------------------------

### GET /<api>/members/find

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Finds members based on various criteria such as list ID, subscriber email, role, and delivery status.

```APIDOC
## GET /<api>/members/find

### Description
Finds members matching the specified criteria.

### Method
GET

### Endpoint
`/<api>/members/find`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
- **list_id** (str) - Optional - Mailing list ID.
- **subscriber** (str) - Optional - Email, user ID, or partial search string for the subscriber.
- **role** (str) - Optional - Membership role. One of ‘owner’, ‘member’, ‘nonmember’, or ‘moderator’.
- **moderation_action** (str) - Optional - One of the moderation actions: ‘defer’, ‘accept’, ‘discard’, ‘reject’, ‘hold’.
- **delivery_status** (str) - Optional - Delivery status: ‘enabled’, ‘by_user’, ‘by_moderator’, or ‘by_bounces’.
- **delivery_mode** (str) - Optional - Delivery mode: ‘plaintext_digests’, ‘mime_digests’, ‘regular’.

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **members** (List[Member]) - A list of Member objects matching the criteria.
```

--------------------------------

### Get Mailing List Owners

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves the owners of a specific mailing list. Owners have the highest level of administrative control over the list.

```python
owners = await mailing_list.owners()
```

--------------------------------

### List Pagination and Deletion with MailmanClient

Source: https://context7.com/mailman/mailmanclient/llms.txt

Demonstrates how to paginate through mailing lists and how to delete a specific list using the MailmanClient. It shows fetching a page of lists and iterating through them, as well as direct deletion by list object or email address.

```python
page = client.get_list_page(count=10, page=1)
print(f"Page {page.nr}, Total: {page.total_size}")
for mlist in page:
    print(mlist.fqdn_listname)
page = page.next  # Get next page

# Delete a list
dev_list.delete()
# Or: client.delete_list('developers@example.com')
```

--------------------------------

### Get Mailing List Nonmembers

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves a list of users who are not members but may have specific permissions or are otherwise tracked by the mailing list.

```python
nonmembers = await mailing_list.nonmember()
```

--------------------------------

### Manage Mailman Queues

Source: https://context7.com/mailman/mailmanclient/llms.txt

Illustrates how to interact with Mailman's message queues using the Mailman Client. This includes listing all queues and their file counts, and injecting a message into the incoming queue for testing purposes.

```python
from mailmanclient import Client
import time

client = Client('http://localhost:8001/3.1', 'restadmin', 'restpass')

# List all queues
queues = client.queues
for name, queue in queues.items():
    print(f"Queue: {name}")
    print(f"  Files: {len(queue.files)}")

# Inject a message into a queue (useful for testing)
incoming_queue = queues['in']
message = """From: sender@example.com
To: developers@example.com
Subject: Test Message
Message-ID: <test123@example.com>

This is a test message.
"""

incoming_queue.inject('developers.example.com', message)

# Wait for processing
while len(incoming_queue.files) > 0:
    time.sleep(0.5)
print("Message processed")
```

--------------------------------

### Filter and Retrieve Advertised Mailing Lists (Python)

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Explains how to modify a mailing list's settings, specifically the 'advertised' flag, and how to retrieve only advertised lists using the client. It also shows paginated retrieval of advertised lists.

```python
>>> my_list.settings['advertised'] = False
>>> my_list.settings.save()
>>> for mlist in client.get_lists(advertised=True):
...     print(mlist.fqdn_listname)
test-2@example.com
test-3@example.com
test-3@example.net
test-announce@example.com

>>> page = client.get_list_page(count=2, page=1, advertised=True)
>>> for m_list in page:
...     print(m_list.fqdn_listname)
test-2@example.com
test-3@example.com
```

--------------------------------

### Get Mailing List Members

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves all members (subscribers) of a specific mailing list. This provides a list of individuals subscribed to the list.

```python
subscribers = await mailing_list.members()
```

--------------------------------

### Get User's Addresses

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves all email addresses associated with a specific user in Mailman Core. This function is part of the User object's capabilities.

```python
user_addresses = await user.addresses()
```

--------------------------------

### Manage Site-Wide Ban List - Default

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Shows how to view the site-wide ban list, add new email addresses to it, check for the presence of an address, and iterate through the banned addresses. It also covers pagination of the ban list.

```default
>>> list(client.bans)
[]
>>> banned_anna = client.bans.add('anna@example.com')
>>> print(banned_anna)
anna@example.com
>>> 'anna@example.com' in client.bans
True
>>> print(client.bans.add('bill@example.com'))
bill@example.com
>>> for addr in list(client.bans):
...     print(addr)
anna@example.com
bill@example.com
>>> for addr in list(client.get_bans_page(count=1, page=1)):
...     print(addr)
anna@example.com
>>> for addr in list(client.get_bans_page(count=1, page=2)):
...     print(addr)
bill@example.com
```

--------------------------------

### Manage User Addresses - Python MailmanClient

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Demonstrates how to view, add, and manage multiple email addresses associated with a user. It includes adding a new address, handling attempts to add existing addresses, and using the `absorb_existing` flag for merging user data.

```python
>>> for address in cris.addresses:
...     print(address)
...     print(address.display_name)
...     print(address.registered_on)
cris@example.com
Cris
...

>>> print(cris.add_address('cris.person@example.org'))
cris.person@example.org
>>> print(client.get_address('cris.person@example.org'))
cris.person@example.org

>>> for address in cris.addresses:
...     print(address)
cris.person@example.org
cris@example.com

>>> with print_exception():
...     cris.add_address('dana@example.org')
HTTPError: HTTP Error 400: Address belongs to other user

>>> print(cris.add_address('dana@example.org', absorb_existing=True))
dana@example.org

>>> for address in cris.addresses:
...     print(address)
cris.person@example.org
cris@example.com
dana@example.org
```

--------------------------------

### Get Mailman Member Details

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Retrieves details of a specific member from a mailing list. It takes the list name and member's email address as input and returns a Member object.

```python
print(client.get_member('test-2@example.com', 'cris@example.com'))
```

--------------------------------

### Get Mailing List Roster by Role

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/async.md

Retrieves members of a specific mailing list based on their role (e.g., owner, member, moderator). This allows for granular access to list membership.

```python
members = await mailing_list.get_roster('member')
```

--------------------------------

### Set Member Moderation Action - Python

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Demonstrates how to retrieve a member, check their current moderation action, set a new action (e.g., 'hold'), save the changes, and verify the update.

```python
>>> bill_member = test_one.get_member('bill@example.com')
>>> print(bill_member.moderation_action)
None
>>> bill_member.moderation_action = 'hold'
>>> bill_member.save()
>>> print(test_one.get_member('bill@example.com').moderation_action)
hold
```

--------------------------------

### Retrieve Individual Membership Details

Source: https://gitlab.com/mailman/mailmanclient/-/blob/master/src/mailmanclient/docs/using.md

Demonstrates how to fetch a specific membership object by email address from a mailing list and access its properties like role and display name.

```python
cris_test_two = test_two.get_member('cris@example.com')
print(cris_test_two.role)
print(cris_test_two.display_name)
```