API Reference

class mailmanclient.Client(baseurl, name=None, password=None, request_hooks=None)[source]

Access the Mailman REST API root.

Parameters
  • baseurl (str) – The base url to access the Mailman 3 REST API.

  • name (str) – The Basic Auth user name. If given, the password must also be given.

  • password (str) – The Basic Auth password. If given the name must also be given.

  • request_hooks (List[callables]) – Callable hooks to process request parameters before being sent to Core’s API.

add_hooks(request_hooks)[source]

Add a hook to process connections to Mailman’s API.

Hooks are callables that are passed in the parameters of HTTP call made to Mailman Core’ RESt API and are expected to return the same number of parameters back. This can be useful to manipulate parameters and update them, or simply log each call to API.

from mailmanclient.client import Client
client = Client('http://localhost:8001/3.1', <user>, <password>)

def sample_hook(params):
    print(f'Request params are {params}')
    return params

client.add_hook([sample_hook])
Parameters

request_hooks – A list of callables that take in a dictionary of parameters. params is the list of request parameters before the request is made.

property bans

Get a list of all the bans.

Returns

A list of all the bans.

Return type

Bans

property chains

Get a list of all the Chains.

Returns

A list of all the chains in Core.

Return type

List

property configuration

Get the system configuration.

Returns

All the system configuration.

Return type

Dict[str, Configuration]

create_domain(mail_host, base_url=<object object>, description=None, owner=None, alias_domain=None)[source]

Create a new Domain.

Parameters
  • mail_host (str) – The Mail host for the new domain. If you want foo@bar.com” as the address for your MailingList, use “bar.com” here.

  • description (str) – A brief description for this Domain.

  • owner (str) – Email address for the owner of this list.

  • alias_domain (str) – Alias domain.

Returns

The created Domain.

Return type

Domain

create_user(email, password, display_name='')[source]

Create a new User.

Parameters
  • email (str) – Email address for the new user.

  • password (str) – Password for the new user.

  • display_name (str) – An optional name for the new user.

Returns

The created user instance.

Return type

User

delete_domain(mail_host)[source]

Delete a Domain.

Parameters

mail_host (str) – The Mail host for the domain you want to delete.

delete_list(fqdn_listname)[source]

Delete a MailingList.

Parameters

fqdn_listname (str) – Fully qualified name of the MailingList.

property domains

Get a list of all Domains.

Returns

All the domains on the system.

Return type

List[Domain]

find_lists(subscriber, role=None, count=50, page=1, mail_host=None)[source]

Given a subscriber and a role, return all the list they are subscribed to with given role.

If no role is specified all the related mailing lists are returned without duplicates, even though there can potentially be multiple memberships of a user in a single mailing list.

Parameters
  • subscriber (str) – The address of the subscriber.

  • role (str) – owner, moderator or subscriber.

  • count (int) – Number of entries per-page (defaults to 50).

  • page (int) – The page number to return (defaults to 1).

  • mail_host (str) – Domain to filter results by.

Returns

A filtered list of mailing lists with given filters.

Return type

List[MailingList]

find_users(query)[source]

Find users with query string matching display name and emails.

Parameters
  • query (str) – The string to search for. The search string is case insensitive as core doens’t care about the case.

  • count (int) – Number of entries per-page (defaults to 50).

  • page (int) – The page number to return (defaults to 1).

find_users_page(query, count, page)[source]

Same as find_users() but allows for pagination.

Parameters
  • query (str) – The string to search for. The search string is case insensitive as core doens’t care about the case.

  • count (int) – Number of entries per-page (defaults to 50).

  • page (int) – The page number to return (defaults to 1).

get_address(address)[source]

Given an Email Address, return the Address object.

Parameters

address (str) – Email address.

Returns

The Address object for given email address.

Return type

Address

get_bans_page(count=50, page=1)[source]

Get a list of all the bans with pagination.

Parameters
  • count (int) – Number of entries per-page (defaults to 50).

  • page (int) – The page number to return (defaults to 1).

Returns

Paginated list of banned addresses.

Return type

Page of BannedAddress

get_domain(mail_host, web_host=<object object>)[source]

Get Domain by its mail_host.

get_list(fqdn_listname)[source]

Get a MailingList object.

Parameters

fqdn_listname (str) – Fully qualified name of the MailingList.

Returns

The mailing list object of the given fqdn_listname.

Return type

MailingList

get_list_page(count=50, page=1, advertised=None, mail_host=None)[source]

Get a list of all MailingList with pagination.

Parameters
  • count – Number of entries per-page (defaults to 50).

  • page – The page number to return (defaults to 1).

  • advertised – If marked True, returns all MailingLists including the ones that aren’t advertised.

  • mail_host – Domain to filter results by.

get_lists(advertised=False)[source]

Get a list of all the MailingLists.

Parameters

advertised (bool) – If marked True, returns all MailingLists including the ones that aren’t advertised.

Returns

A list of mailing lists.

Return type

List(MailingList)

get_member(fqdn_listname, subscriber_address)[source]

Get the Member object for a given MailingList and Subsciber’s Email Address.

Parameters
  • fqdn_listname (str) – Fully qualified address for the MailingList.

  • subscriber_address (str) – Email Address for the subscriber.

Returns

A member of a list.

Return type

Member

get_member_page(count=50, page=1)[source]

Return a paginated list of Members.

Parameters
  • count (int) – Number of items to return.

  • page (int) – The page number.

Returns

Paginated lists of members.

Return type

Page of Member.

get_nonmember(fqdn_listname, nonmember_address)[source]

Get the Member object for a given MailingList and Non-member’s Email.

Parameters
  • fqdn_listname (str) – Fully qualified address for the MailingList.

  • subscriber_address (str) – Email Address for the non-member.

Returns

A member of a list.

Return type

Member

get_templates_page(count=25, page=1)[source]

Get paginated site-context templates.

Returns

Paginated list of templates of site context.

Return type

Page of Template

get_user(address)[source]

Given an Email Address, return the User it belongs to.

Parameters

address (str) – Email Address of the User.

Returns

The user instance that owns the address.

Return type

User

get_user_page(count=50, page=1)[source]

Get all the users with pagination.

Parameters
  • count (int) – Number of entries per-page (defaults to 50).

  • page (int) – The page number to return (defaults to 1).

Returns

Paginated list of users on Mailman.

Return type

Page of User

property lists

Get a list of all MailingLists.

Returns

All the mailing lists.

Return type

list(MailingList)

property members

Get a list of all the Members.

Returns

All the list memebrs.

Return type

List[Member]

property pipelines

Get a list of all Pipelines.

Returns

A list of all the pipelines in Core.

Return type

List

property preferences

Get all default system Preferences.

Returns

System preferences.

Return type

Preferences

property queues

Get a list of all Queues.

Returns

A list of all the queues in Core.

Return type

List

set_template(template_name, url, username=None, password=None)[source]

Set template in site-context.

Parameters
  • template_name (str) – The template to set.

  • url (str) – The URL to fetch the template from.

  • username (str) – Username for access to the template.

  • password (str) – Password for the username to access templates.

property styles

All the default styles in Mailman Core.

Returns

All the styles in Core.

Return type

Styles

property system

Get the basic system information.

Returns

System information about Mailman Core

Return type

Dict[str, str]

property templates

Get all site-context templates.

Returns

List of templates for the site context.

Return type

TemplateList

property users

Get all the users.

Returns

All the users in Mailman Core.

Return type

List[User]

class mailmanclient.Domain(connection, url, data=None)[source]
add_owner(owner)[source]
property base_url
create_list(list_name, style_name=None)[source]
get_list_page(count=50, page=1, advertised=None)[source]
get_lists(advertised=None)[source]
property lists
property owners
remove_all_owners()[source]
set_template(template_name, uri, username=None, password=None)[source]
property templates
property web_host
class mailmanclient.MailingList(connection, url, data=None)[source]
accept_message(request_id)[source]

Shortcut for moderate_message.

Parameters

request_id (str) – The request_id of the held message.

accept_request(request_id)[source]

Shortcut to accept a subscription request.

add_moderator(address, display_name=None)[source]

Add a list moderator.

Parameters
  • address (str) – Email address of the moderator.

  • display_name (str) – Display name of the moderator.

add_owner(address, display_name=None)[source]

Add a list owner.

Parameters
  • address (str) – Email address of the owner.

  • display_name (str) – Display name of the Owner.

add_role(role, address, display_name=None)[source]

Add a new Member with a specific role.

Parameters
  • role (str) – The role for the new member.

  • address (str) – A valid email address for the new Member.

  • display_name (str) – An optional display name for the Member.

property archivers

Get a list of MailingList archivers.

property bans

A list of banned addresses for this MailingList.

defer_message(request_id)[source]

Shortcut for moderate_message.

Parameters

request_id (str) – The request_id of the held message.

defer_request(request_id)[source]

Shortcut to defer a subscription request.

discard_message(request_id)[source]

Shortcut for moderate_message.

Parameters

request_id (str) – The request_id of the held message.

discard_request(request_id)[source]

Shortcut to discard a subscription request.

find_members(address=None, role=None, page=None, count=50)[source]

Find a Mailinglist’s members.

This provides a filtering API for list’s Members including, non-members, owners and moderators by speciying the role.

Parameters
  • address (str) – Member’s address.

  • role (str) – Member’s role.

  • page (int) – Page number for paginated results.

  • count (int) – Number of results per-page for paginated results.

get_bans_page(count=50, page=1)[source]

Get a paginated list of bans for this MailingList.

Parameters
  • page (int) – Page number for paginated results.

  • count (int) – Number of results per-page for paginated results.

get_held_count()[source]

Get a count of held messages for the MailingList.

get_held_message(held_id)[source]

Get a single held message for MailingList.

Parameters

held_id (int) – Held message id to get.

get_held_page(count=50, page=1)[source]

Paginated list of held messages for the MailingList.

Parameters
  • page (int) – Page number for paginated results.

  • count (int) – Number of results per-page for paginated results.

get_member(email)[source]

Get a Member of the list.

Parameters

address – The email address of the member for this list.

Returns

A member proxy object.

get_member_page(count=50, page=1, fields=None)[source]

Return a paginated list of MailingList’s members.

Parameters
  • count (int) – Count of members in one page.

  • page (int) – The page number.

get_nonmember(email)[source]

Get a non-member of the list.

Parameters

address – The email address of the non-member for this list.

Returns

A member proxy object.

get_request(token)[source]

Get an individual pending request for the given token.

Parameters

token – The token for the request.

Returns

The request dictionary.

get_requests(token_owner=None, request_type='subscription')[source]

Return a list of dicts with subscription requests.

This is the new API for requests which allows filtering via token_owner since it isn’t possible to do so via the property requests.

Parameters
  • token_owner – Who owns the pending requests? Should be one in ‘no_one’, ‘moderator’ and ‘subscriber’.

  • request_type – The type of pending request. Value should be in ‘subscription’ or ‘unsubscription’. Defaults to ‘subscription’.

get_requests_count(token_owner=None)[source]

Return a total count of pending subscription requests.

This should be a faster query when all the requests aren’t needed and only a count is needed to display on the badge in List’s settings page.

Parameters

token_owner – Who owns the pending requests? Should be one in ‘no_one’, ‘moderator’ and ‘subscriber’.

Returns

The count of pending requests.

get_roster(roster, fields=None)[source]

Get roster of the MailingList.

If the fields is specified without self_link and address, they are added since it is required for returning the response.

Parameters
  • roster (str) – One of the Membership rosters from ‘owner’, ‘moderator’, ‘member’ and ‘nonmember’.

  • fields (List[str]) – List of Member’s fields to fetch from the API. Skipping certain fields can speed up the API response when they aren’t required since they need to be fetched from database individually.

property header_matches

A list of header-match rules for the MailingList.

property held

Held messages of a MailingList..

is_member(address)[source]

Given an address, checks if the given address is subscribed to this mailing list.

is_moderator(address)[source]

Given an address, checks if the given address is a moderator of this mailing list.

is_owner(address)[source]

Given an address, checks if the given address is an owner of this mailing list.

is_owner_or_mod(address)[source]

Given an address, checks if the given address is either a owner or a moderator of this list.

It is possible for them to be both owner and moderator.

manage_request(token, action)[source]

Alias for moderate_request, kept for compatibility

mass_unsubscribe(email_list)[source]

Unsubscribe a list of emails from a mailing list.

This function return a json of emails mapped to booleans based on whether they were unsubscribed or not, for whatever reasons

Parameters

email_list – list of emails to unsubscribe

property members

All MailingList members.

moderate_message(request_id, action, comment=None)[source]

Moderate a held message.

Parameters
  • request_id (Int.) – Id of the held message.

  • action (String.) – Action to perform on held message.

  • comment (str) – The reason for action, only supported for rejection.

moderate_request(request_id, action, reason=None)[source]

Moderate a subscription request.

Parameters
  • action (str.) – accept|reject|discard|defer

  • reason (str) – The reason associated with rejections.

property moderators

All MailingList moderators.

property nonmembers

All MailingList non-members.

property owners

All MailingList owners.

reject_message(request_id, reason=None)[source]

Shortcut for moderate_message.

Parameters
  • request_id (str) – The request_id of the held message.

  • reason (str) – An optional reason for rejection of the message.

reject_request(request_id)[source]

Shortcut to reject a subscription request.

remove_moderator(address)[source]

Remove a list moderator.

Parameters

address (str) – Email address of the moderator to remove.

remove_owner(address)[source]

Remove a list owner.

Parameters

address (str) – Email address of the owner to remove.

remove_role(role, address)[source]

Remove a list Member with a specific Role.

Parameters
  • role (str) – The role for the new member.

  • address (str) – A valid email address for the new Member.

property requests

See get_requests().

set_template(template_name, uri, username=None, password=None)[source]

Set a MailingList template URI.

Parameters
  • template_name (str) – The name of the template.

  • uri (str) – The URI to fetch the template.

  • username (str) – Username for fetching template from uri.

  • password (str) – Password for fetching template from uri.

property settings

All MailingList settings.

subscribe(address, display_name=None, pre_verified=False, pre_confirmed=False, pre_approved=False, invitation=False, send_welcome_message=None, delivery_mode=None, delivery_status=None)[source]

Subscribe an email address to a mailing list.

Parameters
  • address (str) – Email address to subscribe to the list.

  • display_name (str) – The real name of the new member.

  • pre_verified (bool) – True if the address has been verified.

  • pre_confirmed (bool) – True if membership has been approved by the user.

  • pre_approved (bool) – True if membership is moderator-approved.

  • invitation (bool) – True if this is an invitation to join the list.

  • send_welcome_message (bool) – True if welcome message should be sent.

  • delivery_mode (str. One between 'regular', 'plaintext_digests', 'mime_digests', 'summary_digests'.) – Delivery mode of the Member.

  • delivery_status (str. One between 'enabled', 'by_owner', 'by_moderator', 'by_user'.) – Delivery status of the Member.

Returns

A member proxy object.

property templates

Get a list of MailingList templates.

unsubscribe(email, pre_confirmed=None, pre_approved=None)[source]

Unsubscribe an email address from a mailing list.

Parameters
  • address (str) – Email address to unsubscribe.

  • pre_confirmed (bool) – True if unsubscribe is approved by the user.

  • pre_approved (bool) – True if unsubscribe is moderator-approved.

property unsubscription_requests

Get a list of subscription requests pending moderator Approval.

class mailmanclient.ListArchivers(connection, url, mlist)[source]

Represents the activation status for each site-wide available archiver for a given list.

class mailmanclient.Bans(connection, url, data=None, mlist=None)[source]

The list of banned addresses from a mailing-list or from the whole site.

add(email)[source]
find_by_email(email)[source]
remove(email)[source]
class mailmanclient.BannedAddress(connection, url, data=None)[source]
property mailinglist
class mailmanclient.HeaderMatches(connection, url, mlist)[source]

The list of header matches for a mailing-list.

add(header, pattern, action=None, tag=None)[source]

Add a new HeaderMatch rule to the MailingList.

Parameters
  • header (str) – The header to consider.

  • pattern (str) – The regular expression to use for filtering.

  • action (str) – The action to take when the header matches the pattern. This can be ‘accept’, ‘discard’, ‘reject’, or ‘hold’.

find(header=None, tag=None, action=None)[source]

Find a set of HeaderMatch rules.

Parameters
  • header (str) – The header to consider.

  • tag (str) – The tag associated with header.

  • action (str) – The action to take when the header matches the pattern. This can be ‘accept’, ‘discard’, ‘reject’, or ‘hold’.

class mailmanclient.HeaderMatch(connection, url, data=None)[source]
class mailmanclient.Member(connection, url, data=None)[source]
property address
unsubscribe()[source]

Unsubscribe the member from a mailing list.

property user
class mailmanclient.User(connection, url, data=None)[source]
add_address(email, absorb_existing=False)[source]

Adds another email adress to the user record and returns an _Address object.

Parameters
  • email (str.) – The address to add

  • absorb_existing (bool.) – set this to True if you want to add the address even if it already exists. It will import the existing user into the current one, not overwriting any previously set value.

property addresses
property preferred_address

Preferred address of a User.

New in version 3.2.3.

Returns

Address or None.

property subscription_list_ids
property subscriptions
class mailmanclient.Addresses(connection, url, data=None)[source]
find_by_email(email)[source]
remove(email)[source]
class mailmanclient.Address(connection, url, data=None)[source]
unverify()[source]
property user
property verified
verify()[source]
class mailmanclient.HeldMessage(connection, url, data=None)[source]
accept()[source]

Shortcut for moderate.

defer()[source]

Shortcut for moderate.

discard()[source]

Shortcut for moderate.

moderate(action, comment=None)[source]

Moderate a held message.

Parameters

action (String.) – Action to perform on held message.

reject(reason=None)[source]

Shortcut for moderate.

Parameters

reason – An optional reason for rejecting the held message.

class mailmanclient.Preferences(connection, url, data=None)[source]
delete()[source]
class mailmanclient.Settings(connection, url, data=None)[source]
class mailmanclient.Queue(connection, url, data=None)[source]
property files
inject(list_id, text)[source]