mailman-api¶
Release v0.3rc3
mailman-api provides a daemon that will listen to HTTP requests, providing access to a REST API that can be used to interact with a locally-installed Mailman (version 2) instance.
mailman-api is tested with Python 2.7 and depends on:
- paste >= 1.7
- bottle >= 0.11.6
mailman-api is a work in progress. Contributions are welcome. Feel free to fork and contribute!
Quickstart¶
Installation¶
Distro Packages¶
We are currently working to provide linux packages (deb and rpm). Stay tunned!
Running the Sevice¶
To start the service manually just run the mailman-api command.
If you installed mailman-api from a distribution package you should be able to start your service by running service mailman-api start.
Usage: mailman-api [options]
- Options:
-h, --help show this help message and exit -b BIND, --bind=BIND Bind address. Default: ‘127.0.0.1:8124’. --allow-from=ALLOW_FROM IPs to allow incoming requests. By deufalt only allow connections from ‘127.0.0.1’. -l MAILMANLIB_PATH, --mailman-lib-path=MAILMANLIB_PATH Path to mailman libs directory. Default: ‘/usr/lib/mailman’. -d, --debug Print debug information
API Documentation¶
Requests can be made to any of the URI’s below, strictly using the HTTP methods indicated.
The body of all responses contains valid JSON objects. Unless otherwise noted, successful requests get as response a 200 (OK) status code for response, and true in the response body. Failed requests will get responses with some HTTP error code in the 400s, and a string describing the problem in the response body.
Supported methods:
API V1¶
list_lists¶
Lists existing mailing lists on the server.
Method: GET
URI: /
Returns a list of the mailing lists that exist on this server.
subscribe¶
Adds a new subscriber to the list called <listname>
Method: PUT
URI: /<listname>
Parameters:
- address: email address that is to be subscribed to the list.
- fullname: full name of the person being subscribed to the list.
- digest: if this equals true, the new subscriber will receive digests instead of every mail sent to the list.
unsubscribe¶
Unsubscribe an email address from the mailing list.
Method: DELETE
URI: /<listname>
Parameters:
- address: email address that is to be unsubscribed from the list
members¶
Lists subscribers for the listname list.
Method: GET
URI: /<listname>
Returns an array of email addresses.
sendmail¶
Posts an email to the mailing list.
Method: POST
URI: /<listname>/sendmail
Parameters:
- name_from: name of the poster
- email_from: email address of the poster
- subject: the subject of the message
- body: the body of the message.
- in_reply_to (optional): Message-ID of the message that is being replied to, if any.
API V2¶
list_lists¶
Lists existing mailing lists on the server.
Method: GET
URI: /v2/
Returns a list of dictionaries the mailing lists and its public attributes that exist on this server.
create_list¶
Create a mail list.
Method: POST
URI: /v2/lists/<listname>
Parameters:
- admin: email of list admin
- password: list admin password
- subscription_policy: 1) Confirm; 2) Approval; 3)Confirm and approval.
Default is Confirm (1) * archive_privacy: 0) Public; 1) Private. Default is Public (0)
subscribe¶
Adds a new subscriber to the list called <listname>
Method: PUT
URI: /v2/subscribe/<listname>
Parameters:
- address: email address that is to be subscribed to the list.
- fullname: full name of the person being subscribed to the list.
- digest: if this equals true, the new subscriber will receive digests instead of every mail sent to the list.
unsubscribe¶
Unsubscribe an email address from the mailing list.
Method: DELETE
URI: /v2/subscribe/<listname>
Parameters:
- address: email address that is to be unsubscribed from the list
members¶
Lists subscribers for the listname list.
Method: GET
URI: /v2/members/<listname>
Returns an array of email addresses.
sendmail¶
Posts an email to the mailing list.
Method: POST
URI: /v2/sendmail/<listname>
Parameters:
- name_from: name of the poster
- email_from: email address of the poster
- subject: the subject of the message
- body: the body of the message.
- in_reply_to (optional): Message-ID of the message that is being replied to, if any.
Licensing Information¶
Copyright (C) 2013-2014 Sergio Oliveira Campos
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.