Christian Schneider writes:
My aim is to provide one high-level script for the daily task of list creation.
I'll try to get you started. Mark is likely to have comments or improvements.
If you're on-host, list creation can be done with the 'mailman' utility. The point of the REST API is to allow "arms length" operation by arbitrary software, not necessarily on the same host.
The create-list script itself should be a bash- or perl-script (I am not very familiar with python - SORRY ;-) )
The REST API is script-language-agnostic. It's a bit clumsy compared to using the mailmanclient Python API, but using the REST API, any scripting or programming language would suffer from that.
I would like the scripts to trigger some curl-calls on the mailman server (from outside the mailman shell and even from outside the virtual environment)
It's your call, but are you sure the commands provided by the 'mailman' utility don't do what you need?
- Can I succeed with this plan? (Are curl-calls sufficient? Is it possible from outside the virtual environment?)
Yes, you can do anything using curl that the REST API can do. The virtual environment is only relevant to controlling Mailman from Python. If you are using the REST API, you need a running Mailman, which will already be running in the correct virtual environment.
However, calling curl from a script is very clumsy. You will need to trap errors such as "user exists" and so on. You probably need to parse the response as well as check the HTTP status.
- Is this a viable curl-call to create a user?: curl -X POST -u 'admin-user:<password>' -H "Content-Type: application/json" -d '{ "email": "peter.rabbit@example.org", "display_name": "Peter Rabbit", "password": "secret" }' http://localhost:8001/3.1/users
The "admin-user" in this command is the "restadmin" user, not the list-owner. I think in the 'create-list' command you meant the --admin-user to be the list owner.
Also, the "password" attribute is not very useful in Mailman 3. The only authorized user of the REST API is the restadmin user. There is no provision for access by other users. To authenticate other users, you will need to provide an alternative authentication database, such as .htpasswd validated by a front-end such as Apache. In a full Mailman suite installation, administrative and subscriber authentication is managed by Django, not by Mailman core.
- and in a second step can I assign this user to a list as owner with a curl-call like this?: curl -X POST -u 'admin-user:<password>' -H "Content-Type: application/json" -d '{ "list_id": "newsletter.lists.example.org", "subscriber": "peter.rabbit@example.org", "role": "owner" }' http://localhost:8001/3.1/members
Yes.
- What about the commits that are used while operating in mailman shell?
Not relevant. "mailman shell" is intended for experimentation, so an explicit commit function is provided to trigger a backend database commit. This allows you to fix typos before committing, or even to exit without changing the database if you think you made a big mistake.
In the REST API, each mutating REST call is a single database transaction and the commit is triggered automatically. If you have a multiple call script and something goes wrong in a later call, you will have to unwind any calls that succeeded by hand.
- In the unlikely event that I change from the dark side to the good side i.e. "python programming" ;-) is there a "to-the-point" reference for IListManager, IUserManager etc. giving available functions (with parameters) in a kind of list way? (the example kind of documentation referenced above is good, but where can I find a list of all functions?)
No. https://docs.mailman3.org/projects/mailman/en/release-3.1/src/mailman/rest/d... is fairly complete, but the only truly complete lists are in the source. You can also go into the Mailman shell, import the relevant modules and use the help() function.
- I think the starting point for managing lists with python is here: https://docs.mailman3.org/projects/mailman/en/latest/src/mailman/commands/do... right?
Yes.
- Going the python way will require to enter the virtual environment, right? (otherwise the libraries, environment variables etc. are not available...I think)
For development, yes. It would be very annoying. However, in production, you would most likely use "mailman shell -r script". In that case you can invoke the script with the full path "/path/to/venv/bin/mailman" and place "script" in the venv/bin directory. This will automatically invoke the Python portion of the virtual environment (eg, sys.path will be set appropriately), but not the shell environment. Then you can use a shell script or function to abbreviate the command.
-- GNU Mailman consultant (installation, migration, customization) Sirius Open Source https://www.siriusopensource.com/ Software systems consulting in Europe, North America, and Japan